Sharp Words

Write for the right audience is (or should be) one of the golden rules of any type of writing. For example, if you’re writing a novel for children, don’t bog the story down in too much flowery description; if you’re preparing a pamphlet listing rubbish bin collections, keep timetables and lists simple enough for people of any level of education to understand.

This simple rule can be broken down even further for technical writers.

1. Know the level of your audience.
Are you writing a manual for novice users? Are you writing one for system administrators or developers who will probably know the technical concepts better than you do? Are you writing for an academic journal where complex terms will be fully understood by readers?

Make sure you use the right level of language for your readers, and try to avoid either confusing or patronising them. If you have multiple levels of readers, you can pitch your document somewhere in the middle, but don’t forget to explain things for those with lower levels of prior knowledge.

2. Explain unfamiliar concepts.
This ties into the previous point. For someone who has never used a computer before, include a diagram which names each part of a window, for example. Don’t assume that they will know how to click a button – explain it!

Do likewise with other terms and concepts that may be unfamiliar – it’s better to explain it than to leave someone floundering. People who know what it means can skip it.

This is where glossaries and appendices of reference material can be really useful, but don’t force readers to have to go looking in the glossary fifteen times a page.

And always remember to spell out acronyms, initials and other abbreviations the first time they are used!

3. Don’t over-complicate.
Don’t use clever-sounding language for the sake of it. It doesn’t add anything to your writing, and can be confusing – and difficult to translate! There’s no need to write ‘There is no possibility that you can’ when ‘You cannot’ works much better.

Don’t use jargon for the sake of it, either – or if you must, explain it (as per #2).

4. Don’t over-simplify.
This might sound like a contradiction of the previous point, but it isn’t. Sometimes technical documents (and I include other types of scientific, medical and scholarly documents here) contain complex concepts which will lose their significance if reduced to language that’s too simple.

If you have to explain complicated ideas, keep your explanation as straightforward as possible and explain terms that will be unfamiliar to your audience where necessary (as in #2); but don’t dumb it down to the point that you lose meaning or patronise your readers.

In summary: know the level of your readers and write to suit them! Even consider breaking a document into ‘basic’ and ‘advanced’ user guides if necessary. Don’t try to be too clever and keep things straightforward, but avoid making your writing too stupid, or so simple that your readers are annoyed.

All of which sounds complicated… but it isn’t. It just takes practice – and where possible, some guinea pigs to test your documents on!

————–
If you have any questions or comments about this article, or any suggestions for future posts, please comment on this post or email me via my contact form.
Technical Writing Tuesdays: index of posts