Writing for developers, part 2

Last week, I posted about how similar the process of writing is to the Red-Green-Refactor cycle of test-driven development. Breaking it down to three stages helps to get more done and at higher level of quality. Programming is a form of writing after all.

Haven’t read the first part yet? Check it out here.

This post follows up about clarity and context, both important aspects of any writing that you do; whether it’s a Slack message or full book.

Three words: Clarity

The primary goal of most writing is to communicate a message. We may also write to impress, to entertain or to persuade. And all of those are valid aspirations, but no matter what you do, your piece will fall flat unless its message is clear.

What makes writing unclear? Well, many things. Overly rigid tone, complicated structure, difficult words, grammar mistakes, tangents and jumping between topics to name a few, but it could be anything.

Let’s take it from the other way around. There’s one thing that makes writing clearer, and that is cutting.

When writing the first draft, you’re laying down the subject matter — anything that you think should go into the piece as it comes out of your head. Depending on how experienced a writer you are, this will make more or less sense. But it will rarely be perfect.

Cutting and rewriting means removing anything that isn’t your message. Does it support what you want to say? And is it the best way to put it? If not, take it out or rewrite it.

Here are a few ideas on how to put your literary scalpel to use.

Difficult words

Always use a simple word over a fancy one. It may not sound as impressive, but it will be much easier to read and understand. The truth is that anyone you might want to impress won’t fall for a couple of frilly words anyway.

This is especially true for using jargon. There so much of it in computing and we often don’t even realise that other people don’t understand much of it. Mind any industry-specific words or acronyms in your copy and use a simpler alternative wherever possible. Particularly when writing for nontechnical audience.

Complicated sentences

Last year, I read a few books about punctuation. They were all really helpful and I learned a few things. But with my freshly acquired grammar confidence, I started putting semicolons everywhere. And while at least some of the sentences might have been correct, it made my copy clumsier to read and tricky to understand.

Even when the rules of grammar stand on your side, complex structures can obstruct what you’re trying to say. On the contrary, long sentences aren’t necessarily bad, as long as you keep them simple. In fact, varying sentence length from long to short makes your writing feel less monotonous.

A good way of testing this is reading your copy out loud. If you find yourself sounding like somebody from 200 years ago, make your sentences shorter.

Unnecessary words

These are often adverbs like really and very or certain uses of clauses like you know, as I said earlier or as you can see.

I kept stumbling on this in many books, and for a long time, it wasn’t clear to me why writers put so much emphasis on keeping your prose tight. Surely, a superfluous word here and there is fine, as long as it said what I wanted?

Thinking about that a little further, it comes back to clarity again. Unnecessary words blur your message - it takes more reading to get the same amount of information.

Articles and books are made up by many words and if you don’t get into the habit of cutting the loose ones, they will add up and tire your readers.

Kill your darlings

Occasionally, there will be a word, phrase or sentence that you’ll be really happy about. Like a joke or a clever Star Wars reference and you’ll be thinking how to make it work in your piece. By all means use it, but never at the expense of clarity.

As frustrating as it can be to see a clever pun go, be strong and “Kill your darlings!” as Stephen King aptly says.

Context is king

Writing is a means of communication from you - the sender - to your readers on the receiver end. Good writing is appropriate to the context it will be received in.

Are your audience Cambridge academics or Shoreditch hipsters? Is the occasion a release of a new feature or fix for a fatal issue that caused data loss to your users? Sometimes the context is obvious, other times less so.

Is your audience technical? Are they familiar with what you’re writing about? Define your target group and write for them. This decision will affect most of your further choices regarding content, tone, style and structure and make them surprisingly simple.

Your style in a dissertation will be slightly more formal with citations all over. In a note to hipsters, you probably shouldn’t mention Starbucks too much. You get the idea.

It works best if you’re part of the audience yourself, albeit that’s not always possible. If you’re unsure who they are, do some research first.

Until the next time

Writing is a lot like programming, except there are much fewer rules that are set in stone (and many more exceptions). Clarity is vague (and it means different things to different people), but it’s the single most important aspiration of any written piece, so that the readers get what the writer is saying. Context is a great way to start thinking about your writing. How can you make this message as clear as possible to a particular audience?

In the next post, we’ll dive a little deeper again to talk about style and structure.