Latest posts by techwriter (see all)
- How NOT to Look for a Writing Job (1) - January 22, 2017
- Hazards of Poorly Written Technical Documentation - December 26, 2016
- Get an ‘A’ on Your Next Research Paper With These 6 Simple Steps - November 28, 2016
Creating a user guide is a meticulous job. Grammar mistakes, inappropriate style, wordiness and unclear instructions are considered by users as defects of the software product itself, which produces a negative impact on the credibility of the product and the company that made it. Editors and bloggers may give such programs negative reviews, swaying potential customers to competing products.
In this article, I am going to describe typical mistakes that may be found in user guides and give recommendations on how to avoid them. The recommendations below are not an exhaustive list of all possible mistakes and therefore should be used alongside with the rules you already follow when creating a user guide.
So, what mistakes are common in user guides?
1. Unclear description of a procedure
Write procedures as clearly as possible, so that the user understands what to do at first glance. First, tell where a procedure takes place and then what the user needs to do (click, open, select, close, etc.).
Wrong: Select Open from the File menu.
Right: In the File menu, select Open.
2. Describing multiple steps in a single sentence
Too often writers describe a complex, multi-step procedure in a single sentence. To keep the description of a procedure clear, you need to separate a complex sentence into steps.
Wrong: Please send us a screenshot (we recommend using Jet Screenshot for taking it) that shows what the problem is.
Please send us a screenshot, which shows the problem.
To take a screenshot, please use Jet Screenshot.
3. Failure to define steps properly
A complex procedure consists of several steps. Each step must describe an action and result. However, there are user guides where action and result are divided into separate steps. It is a common mistake.
1. Select the Phonebook tab.
2. The Phonebook window opens.
3. Click a contact.
4. The contact profile opens.
1.Select the Phonebook tab.
The Phonebook window opens.
2. Click a contact.
The contact profile opens.
1. Select the Phonebook tab.
2. On the Phonebook window, click a contact.
4. Button titles in quotes
In many user guides you can see button titles in quotes. Nowadays this method has become obsolete. Quotes were used back in the days when typing machines had no other option to format text but use quotes or underscore. Now it’s best to write button titles in bold or use upper-case characters.
Wrong: The “Remove” button removes a file from the list.
Right: The REMOVE button removes a file from the list.
Also right: The Remove button removes a file from the list.
5. And / Or
Do not use ‘and / or’ in sentences. It makes your text harder to read and understand, so that the reader has to read sentences over and over again. Instead of ‘and / or’, use ‘… or… or both’.
Wrong: You can convert a file to AVI and/or MP3.
Right: You can convert a file to AVI or MP3, or both.
6. Misuse of terms
An inexperienced writer often makes mistakes in terms.
Wrong: Press the New icon to create a new project.
Right: Click the New icon to create a new project.
The verb ‘press’ means pressing a key on the keyboard, while ‘click’ means clicking on an icon in the program window using the mouse.
7. Future tense
There are many user guides where the result of an action is expressed with a future tense. For example: ‘When you click the OK button, the program will start the conversion’. That’s a mistake. Because of the future tense the reader feels uncertain and may want to ask unnecessary questions like: ‘When does the conversion start?’ or ‘What if it doesn’t start?’ Why readers may ask these questions? The answer is simple.
The verb ‘will’, which nowadays is used to express future, initially had the form ‘willian’. It was a modal verb expressing volition. Sometimes ‘willian’ was used when people talked about their future plans as there was no special form for future in Old English. Over time, ‘willian’ reduced to ‘will’ but it still preserves its original modal meaning. For example, volition is clearly seen in the phrase: ‘The pen won’t write’.
Therefore, when you read the sentence ‘When you click the OK button, the program will start the conversion’, the verb ‘will’ expresses both future and volition. It sounds as if the program ‘wanted’ to begin the conversion. But what if it doesn’t ‘want’ to? To avoid ambiguity, the present tense should be used.
Wrong: When you click the OK button, the program will start the conversion.
Right: When you click the OK button, the program starts the conversion.
Technical writers should stick to neutral style. The use of expressive words distracts readers and is considered to be a stylistic mistake that should be avoided.
Wrong: Kill the app.
Right: Close the application.
Wrong: Hit the Search button.
Right: Click the Search button.
User guides should not contain abbreviations and other word reductions.
Right: for example
A term consisting of several words should not be abbreviated if it is used only once in the whole text. However, if the term appears several times, you should put its abbreviation to brackets right after the term is used for the first time. In all further instances an abbreviation should be used to describe this term.
Oxygen Software today introduces an enhanced version of its Oxygen Phone Manager II (OPM II) for Nokia and Vertu phones. The biggest change in OPM II is tested quality support for groundbreaking Series 40 5th Edition of Nokia phones, whose posh look and cool features have won the hearts of millions of people.
User guides are all about clarity and accuracy. To achieve these attributes, one needs solid knowledge of grammar and stylistics. Poorly written documentation can backfire and cause users to feel discomfort and irritation which may lead them to making a choice in favor of your competition. I hope that these tips will help you to make your technical documentation better and easier for the end-users to read.
Roman Korolenko is a Russian translator and owner of Russian translation and press-release distribution service at [http://www.ivan-pr.com]http://www.ivan-pr.co