Technical documentation is not just any text. It is a whole new world with its rules and patterns to follow. This article will explain how technical writers can avoid the most common mistakes when writing a user manual.
Abbreviations
Abbreviations are great. They save us time and effort. We can transmit information faster using abbreviations, and they are relatively easy to memorize.
The problem here is that we tend to abbreviate too much, especially in professional fields (which is only natural: many long terms like feature names, organization names, etc.). The golden rule for you - always explain what an abbreviation means when you first mention it in a help article. Even if you have it explained in all other articles - it doesn’t matter. Your reader needs to be able to understand each article without additional context.
Words That are Easy to Mix Up
There are words that sound similar but are spelled differently and mean different things. Man, these are the worst! They are untrackable by spell-checkers.
Unfortunately, it is still a very demanding task for a regular spell-checker to distinguish ‘your’ and ‘you’re’.
You might think that this kind of mistake is not that serious, and the message of a help topic will be easily understood still. We would like to assure you that such mistakes are far from being harmless - they will most definitely make your readers roll their eyes.
‘Its’ instead of ‘It’s’ can make your user manual look unprofessional.
How to avoid this mix-up? Study the list of some tricky words below and try paying attention to them the next time you write something.
-
Its - it’s
-
Your - you’re
-
Forth - fourth
-
Their - they’re
-
To - too - two
-
Site - sight - cite
-
Write - right
-
New - knew
Complete Sentences
Use only complete sentences in your technical documentation - the ones that have a subject and a predicate.
You can encounter many one-member or elliptical sentences in fiction. It is quite okay for writers to use them. Even more, such sentences are usually of great value in fiction. They create an atmosphere, tension, express a character’s emotional state and so on.
As you know, user manuals are supposed to be neutral. No need to build more tension there - reading technical documentation is stressful enough for many users :)
Of course, there are cases when we don’t need complete sentences. Like, for example, in software documentation, when you just enumerate features. The rest of the help topic though should be comprised with good old two-member sentences.
Contractions
Contractions are the natural way of a language to be more concise while remaining understandable. They originate from oral speech and work their way into writing. But, they they are not used in official documents, user manuals included.
Contractions make things look less corporate and serious.
This Urban Dictionary article nails it:
Contractions should not be used in technical documentation, just like they are not used in contracts and agreements. It is historically so. Just remember this next time y'all’re gonna write an article!
Conclusion
Of course, there are many more of these - the weak spots where mistakes turn up regularly. We’ve covered just a tiny part of the whole thing. But it is a good start.
There are many things you can do to develop top skills any technical writer needs. Start here, and never stop growing as a professional technical communicator.
Happy Technical Writing!
ClickHelp Team