Language and understandable writing

Originally published on Kauri.io, where developers write, share & learn

I appreciate that not everyone who writes documentation is a native English speaker, or even if they are, may not understand the best way to write clearly and concisely. Many native English speakers had our last grammar lesson more than 20 years ago, and have learnt the tips and tricks we now use as professional writers recently. There are three important things to remember to justify the time and effort of making your writing more understandable:

• English is often a default language for technical documentation, so your readers are also not native speakers
• Readers want to trust what you say, and certain language choices can help
• Readers are trying to understand complex subjects, so every little thing you do to make that easier is worth it

While you can spend a lot of time crafting the perfect sentence to explain something, here are a handful of tips to add that dash of clarity your need.

K.I.S.S.

Or Keep it simple (stupid).

Don't use words that add no value. Words for humour or character are fine (but come with complexity), but words that muddy the explanation (and thus the readers understanding) are a distraction. In English, there are words called weasel words that add nothing but syntactical noise. They may be useful in fiction or creative writing, but for explanatory text, they are not useful.

There are common weasel words that you probably use all the time without thinking, such as:

• very
• easy
• just
• only
• simply
• trivial

Certain weasel words such as "easy" and "just" are worse than noise, and they can come across as patronising. These are words that people commonly use, but don't think about their implications. If you say something is "easy", and someone spends 3 hours battling with dependency hell, then it wasn't "easy", and your documentation probably annoyed them. If you are lucky enough that your project, developer experience, and documentation is good quality then you don't need to tell people that it's "easy", they will find that out themselves.

When you edit your first draft (which of course you should!), consider how many words you need to explain a concept. One of the advantages of English is that you can do quite a lot with few words, but many choose to use way more than they need. Continuing the theme of this section, every extraneous word adds syntactical noise that people have to sift through to find the information they need.

Show off

There are words that people use to show off how clever they are, which is comparable to creating overly complicated code for no particular reason but to impress people. Remember that often when we write in English for technical copy (and it is often the lowest common denominator language in our sector), we are writing for international audiences, who are reading in their second or third language. Adding complexity for your indulgence is selfish and doesn't help anyone. If a simpler word does the job, use it. Let your code and ideas speak for how smart you are, not your knowledge of obscure English words.

Write confidently

My final writing advice is a grammatical one, and something more subtle that I spend a lot of my time changing in the text that I edit, but I feel strongly about it. It's the topic of writing confidently. Confident writing helps people believe that what you say is true and accurate, and doesn't leave them unsure if they should believe what you say. There are a couple of small grammatical tricks to help with this that are sometimes hard to apply and may seem unnecessary but pay off in the end.

Strangely, the best explanation is from Stephen King's "on writing", even though it's not flattering of technical writing.

The book is over ten years old, times have changed (I hope). In this extract, he starts discussing adverbs or words that modify other words. He then moves on to discussing the passive voice, which I cover next.

I think timid writers like them for the same reason timid lovers like passive partners. The passive voice is safe. There is no troublesome action to contend with; the subject just has to close its eyes and think of England, to paraphrase Queen Victoria. I think unsure writers also feel the passive voice some how lends their work authority, perhaps even a quality of majesty. If you find instruction manuals and lawyers' torts majestic, I guess it does.

My first piece of advice is to active voice as much as possible. This means making it clear who the actor and subject are in each sentence. There are often situations where this isn't possible or relevant but try it as much as possible. It may not be clear what I mean, so here's an example.

Passive voice

Functions can be used to return a value

Are you sure about that, can they or not?

Active voice

You can use functions to return a value

Ahh, so I can use them!

It's a small change, and might not even be that noticeable in isolation, but throughout an entire article, it does make a difference. It clarifies details, and the active voice gives readers more confidence, as the lack of clarity in passive voice can make it seem like you're not sure.

Confident words

Another trick alongside this (and an example of English vagueness) is using more confident words elsewhere or removing less confident ones. For example, using "can" instead of "may" or "should", or telling the reader directly what they can do instead of making it sound like it's optional. For example:

You should add your key

OK, I feel like I probably have to add my key, but it kind of sounds like it's optional.

Add your key

Right nice and clear, I should add my key.