Plain language is the key to documentation that thrills your users

Many companies write their knowledge base documentation in your typical corporate speak. It creates distance between the company and the individual, as though abdicating responsibility.

It can even be used to disguise unpleasant facts, such as a lack of functionality.  

We’ve all been trained to think that professional language should be stuffy and stilted, devoid of emotion or interest. Professional documents are awash with this practice.

And we wonder why no one can be bothered to read them. The answer?

Write like a human, not a machine.

Happily, the trend is now moving towards using language that is plainer and easier to understand.

It’s especially pronounced in web-based documentation, as it’s much more of a strain to read online than in print. The reader has to work at least twice as hard to sustain attention.

Plain language has a very tangible benefit for your documentation. It makes your writing much easier to comprehend, and this contributes to the overall goal of your documentation – teaching your users how to do something.

What is plain language?

The more ‘fluff’ that you stuff into your docs writing, the more your user has to get through before they can apprehend the meaning of what you’ve written.

As the saying goes, good writers are just good editors. This has a great deal of truth to it. Everyone writes differently, but you’re unlikely to get the final version of your content down the first time you write it. You waste time agonizing over the first draft.

Photo by energepic.com from Pexels 

Instead, write rough, leave your writing for a bit, and then come back to it as a ruthless editor. Cut, cut, cut everything that isn’t plain. It’s hard to do at first because we’re trained to value an excess of language.

That’s why we’ll go into exactly how you can write your docs in plain language.

Strike out any unnecessary words

When we write, we like the sound of our own voice. When information comes onto the page in its raw state, it’s often not in the most succinct form that it could be. We include many words that are actually duplicates or redundant.

For example, instead of saying 'The system is in-built with the capacity to perform automatic integrations', you can just say 'The system can perform automatic integrations'. The latter sounds less pompous, and makes more sense. 

Eliminate any ambiguity

Edit your writing for instructions or descriptions that could be interpreted as having more than one meaning.

Sloppy writing is ambiguous and users will actively have to decide which meaning you are referring to. This wastes mental energy and is not plain language.

For example, saying “I saw a man on a hill with a telescope” can be interpreted in several different ways.

Image: Ryan Wick via Flickr

It can mean:

• There’s a man on a hill, and I’m watching him with my telescope.
• There’s a man on a hill, who I saw, and he has a telescope.
• There’s a man, he’s on a hill, which also has a telescope on it.
• I’m on a hill, and I saw a man through my telescope.
• There’s a man on a hill, and I’m sawing him with his own telescope.

This causes confusion in your user and makes them unsure about what to do next.

Punctuation is the best way to refine your meaning and remove ambiguity. Commas in particular, or breaking up multi-clause sentences into smaller sentences, are two ways.

Use the shortest words possible

Shorter words are better for comprehension. Don’t say ‘in conjunction’ when you can also say ‘also’, just because it sounds smarter.

Go through your work and look for all the words you have used which can be replaced with a shorter equivalent.

Simple words are closely related to short words. Why say ‘accelerate’ when you can say ‘speed up’? It may sound fancier, but in reality you’re just making more work for your user.

Using words that are too pompous can alienate them and cause your documentation to fail.

Ask yourself if there is any particular value in using this particular word over another word. Check out this list of alternative words you can use.

If any technical terms are included, explain them briefly

In any documentation, it will be practically impossible to avoid the use of some technical terms. These are words that are only used in a particular field, and are not expected in everyday discourse.

Where you do use technical terms, make sure to include a short explanation that you keep consistent across your documentation.

Remember to view technical terms as your customers would see them – and not as your internal team would use them. You may refer to a certain feature of your product as a widget, but if all your customers call it a fladoozle then you should say fladoozle.

Don’t force unnecessary terms on your users.

Break up long paragraphs into shorter ones

You’re probably already aware that long paragraphs are deadly nightshade to any internet user. The long wall of text means that a lot of information will be packed together and takes extra work to comprehend.

Try to stick to one point per paragraph, and don’t be afraid of paragraphs that are only one sentence long. Bitesize chunks in the way forward when it comes to using paragraphs in your documentation.

Use ‘you’ as a pronoun

Avoid saying things like ‘the user’ at all costs. Even saying ‘he’, ‘she’ or ‘they’ makes your docs less immediate. Write your docs as though you are narrating a user through a gameplay. If no pronoun is necessary for clear meaning, leave it out.

Image via Colin Woodstock

You can just write your documentation using mainly directives, like ‘Go to your account page’ instead of the dreaded “the user goes to his or her account page”.

Use the active voice

Similarly, to make your docs more immediate use the active rather than the passive voice. Writing in the active voice means the subject is doing the action. The opposite is passive voice, when the subject is having the action done to them.

For example, ‘the dog [subject] chases the ball [object]’ is written in active voice. If we were to reorganise this sentence into passive voice, it would be ‘the ball [object] was chased by the dog [subject].’ The latter is much more wordy, and slower to read, than the former.

We’ve written a whole article on it.

The Hemingway app is an excellent tool for plain language in general. It helps you check for passive choice, as well as break down overly complex sentences.

A note of caution

While plain language is the goal you should be aiming for, there’s something else you should consider when writing your docs.

You should avoid alienating or confusing any non-native audiences with language that is too colloquial. For example, non-native English speakers won’t necessarily understand a term like “hit the button”, versus “click the button”.

Keep this in mind if you’re users are likely to be non-native speakers.

Final remarks

It takes a bit of practise to get your writing into a rhythm that mimics natural speech. The US government has a checklist for making sure you write in plain language.

Plain language is the most accessible form of writing your documentation. Far from making your organisation look unprofessional, it helps you build a closer relationship with your users.

We often like to kid ourselves that the more work we end up with (including documentation) the more valuable the end result is. That’s not the case. Sometimes the majority of the work takes place behind the scenes.

Whittle down as much as you can, leaving you with only what you need rather than what you’re emotionally attached to.

KnowledgeOwl offers dedicated knowledge base software to help you write your best support documentation. Take us for a free spin today.