Typical Mistakes in User Guides and How to Avoid Them

Creating a user guide is a meticulous job. Grammar6. Misuse of terms
mistakes, inappropriate style, wordiness and unclearAn inexperienced writer often makes mistakes in
instructions are considered by users as defects of theterms.
software product itself, which produces a negativeFor example:
impact on the credibility of the product and theWrong: Press the New icon to create a new project.
company that made it. Editors and bloggers may giveRight: Click the New icon to create a new project.
such programs negative reviews, swaying potentialThe verb 'press' means pressing a key on the
customers to competing products.keyboard, while 'click' means clicking on an icon in the
In this article, I am going to describe typical mistakesprogram window using the mouse.
that may be found in user guides and give7. Future tense
recommendations on how to avoid them. TheThere are many user guides where the result of an
recommendations below are not an exhaustive list ofaction is expressed with a future tense. For example:
all possible mistakes and therefore should be used'When you click the OK button, the program will start
alongside with the rules you already follow whenthe conversion'. That's a mistake. Because of the
creating a user guide.future tense the reader feels uncertain and may want
So, what mistakes are common in user guides?to ask unnecessary questions like: 'When does the
1. Unclear description of a procedureconversion start?' or 'What if it doesn't start?' Why
Write procedures as clearly as possible, so that thereaders may ask these questions? The answer is
user understands what to do at first glance. First, tellsimple.
where a procedure takes place and then what theThe verb 'will', which nowadays is used to express
user needs to do (click, open, select, close, etc.).future, initially had the form 'willian'. It was a modal verb
For example:expressing volition. Sometimes 'willian' was used when
Wrong: Select Open from the File menu.people talked about their future plans as there was no
Right: In the File menu, select Open.special form for future in Old English. Over time, 'willian'
2. Describing multiple steps in a single sentencereduced to 'will' but it still preserves its original modal
Too often writers describe a complex, multi-stepmeaning. For example, volition is clearly seen in the
procedure in a single sentence. To keep the descriptionphrase: 'The pen won't write'.
of a procedure clear, you need to separate a complexTherefore, when you read the sentence 'When you
sentence into steps.click the OK button, the program will start the
For example:conversion', the verb 'will' expresses both future and
Wrong: Please send us a screenshot (we recommendvolition. It sounds as if the program 'wanted' to begin
using Jet Screenshot for taking it) that shows what thethe conversion. But what if it doesn't 'want' to? To
problem is.avoid ambiguity, the present tense should be used.
Right:Wrong: When you click the OK button, the program will
Please send us a screenshot, which shows thestart the conversion.
problem.Right: When you click the OK button, the program
To take a screenshot, please use Jet Screenshot.starts the conversion.
3. Failure to define steps properly8. Jargon
A complex procedure consists of several steps. EachTechnical writers should stick to neutral style. The use
step must describe an action and result. However,of expressive words distracts readers and is
there are user guides where action and result areconsidered to be a stylistic mistake that should be
divided into separate steps. It is a common mistake.avoided.
For example:For example:
Wrong:Wrong: Kill the app.
1. Select the Phonebook tab.Right: Close the application.
2. The Phonebook window opens.Wrong: Hit the Search button.
3. Click a contact.Right: Click the Search button.
4. The contact profile opens.9. Abbreviations
Right:User guides should not contain abbreviations and other
1.Select the Phonebook tab.word reductions.
The Phonebook window opens.For example:
2. Click a contact.Wrong: approx.
The contact profile opens.Right: approximately
Also right:Wrong: e.g.
1. Select the Phonebook tab.Right: for example
2. On the Phonebook window, click a contact.A term consisting of several words should not be
4. Button titles in quotesabbreviated if it is used only once in the whole text.
In many user guides you can see button titles inHowever, if the term appears several times, you
quotes. Nowadays this method has become obsolete.should put its abbreviation to brackets right after the
Quotes were used back in the days when typingterm is used for the first time. In all further instances an
machines had no other option to format text but useabbreviation should be used to describe this term.
quotes or underscore. Now it's best to write buttonFor example:
titles in bold or use upper-case characters.Right:
For example:Oxygen Software today introduces an enhanced
Wrong: The "Remove" button removes a file from theversion of its Oxygen Phone Manager II (OPM II) for
list.Nokia and Vertu phones. The biggest change in OPM II
Right: The REMOVE button removes a file from theis tested quality support for groundbreaking Series 40
list.5th Edition of Nokia phones, whose posh look and cool
Also right: The Remove button removes a file fromfeatures have won the hearts of millions of people.
the list.Conclusion
5. And / OrUser guides are all about clarity and accuracy. To
Do not use 'and / or' in sentences. It makes your textachieve these attributes, one needs solid knowledge of
harder to read and understand, so that the reader hasgrammar and stylistics. Poorly written documentation
to read sentences over and over again. Instead ofcan backfire and cause users to feel discomfort and
'and / or', use '... or... or both'.irritation which may lead them to making a choice in
For example:favor of your competition. I hope that these tips will
Wrong: You can convert a file to AVI and/or MP3.help you to make your technical documentation better
Right: You can convert a file to AVI or MP3, or both.and easier for the end-users to read.