RSS 
Email 
Twitter
FacebookThree Simple Mistakes Non-Technical Writers Make
July 27th, 2007 | Posted in Technical Writing 19 Comments »
If you ask someone who has never written technical documentation before to describe a procedure, chances are he or she will give you a document that looks as follows:
- It completely omits numbered steps.
- Each paragraph or line is followed by a full-size screenshot that takes up half the page.
- Quotation marks surround various names somewhat at random.
Fortunately these mistakes are easy to fix.
Steps
When describing a sequence, number each step. Keep the task about 5-10 steps long. If the steps don’t need to be performed in sequence, use bullets instead. The use of steps helps the reader follow along more easily. If you have a long procedure (15-30 steps), break it into multiple tasks.
Screenshots
Only use screenshots when they are necessary for clarification. If a procedure is easy to follow without a screenshot, don’t add unnecessary bulk to the procedure by adding the screenshot. When you do add screenshots, use partial screenshots that focus on the area you’re highlighting. In general, keep the task as concise and light as possible without confusing the reader.
Quotation Marks
When you tell a reader to click a button or select a link, bold the direct object. For example, Click the Print button. Quotation marks often set off words and give them a different meaning. For example, if I wrote, Oh yes, the show was “great” last night, you’d know the show was terrible. Even without this meaning, it’s just better practice to bold direct objects — it helps scanning and allows readers to quickly predict what they’re supposed to click or select.
Other Characteristics
I haven’t said anything about accuracy or the use of styles, but these are also major omissions newbies make. Exactly how accurate are the steps? Chances are a review of the procedure will show some steps were left out, some buttons or links were misnamed, and overall it may be hard to follow.
Is the text structured with specific styles? Probably not. Many new technical writers prefer the inline formatting toolbar. While you may get by with a short document using inline formatting, it’s not good practice and will cost you more time and frustrate you in the long run. Here’s a handout (.pdf) on using styles in Microsoft Word by Pam Treme, a colleague in the Suncoast chapter.
What are some common problems you see in technical writing by beginners?
photo from flickr.com
[...] Johnson posted an interesting blog entry about three simple mistakes that non-technical writers make. What’s interesting is that I’ve seen technical [...]
This is not a “simple” mistake, but a problem I’ve seen repeatedly when an SME writes a manual is assuming that readers will read the whole thing sequentially. Sometimes this is as benign as connectors like “as mentioned previously”. Other times, the whole document “builds a case” in a way where you really can’t understand the later parts unless you read everything up to that point.
The solution is to realize that reader often “dip” into a manual to read just the sections they’re currently interested in. Mentions of material in other sections need explicit and specific cross-references. It’s OK to build up a complex example across several sections, but try to restrict the discussion of the example in a particular section to the parts relevant to the content of that section. This is not always easy, depending on the domain. It may be necessary to recast the document as a tutorial rather than as a manual.
[...] I’d Rather Be Writing – – 20 hours, 4 minutes ago – Feed – Focus 20 hours, 16 minutes ago Three Simple Mistakes Non-Technical Writers Make by tom in Technical Writing If you ask someone who has never written technical documentation [...]
My pet peeve is the careless use of any or all of the following terms – click, click on, select, press, choose, use, activate, etc.
I like “click” as in “click the Submit button,” but what’s most important is to simply choose one terminology and use it consistently.
I LOVE your comment on bolding instead of quoting!! I will happily use this from now on! I’ve often struggled with conveying technical information effectively vs. obeying the nitpickey rules of English because of quotation marks. For instance, proper English would dictate that I write the following sentence thusly:
Click the “File” pulldown menu, click “Save,” and click “PDF.”
While this is grammatically correct it makes the instructions awkward and inaccurate because the contents of the quotation marks ought to reflect the EXACT wording to be found on-screen. Bolding deftly skirts around this problem!
A common mistake amateurs make is to use lots of passive voice and adopt a very stiff, formal tone. For instance:
“The next menu will be displayed by pressing the Enter key.”
When any self respecting pro would write something like:
“To see the next menu, press the Enter key.”
In short documents that explain fairly simple procedures it’s not really a problem. In larger documents it really makes a difference, not least because professionals tend to make such documents up to 30% shorter.
As someone who is new to this all, I’d definitely recommend that we should all get rid of our attachment to the formal, passive voice and write as advised by roGER above.
roGER, Dawn: You’re right about the passive voice. It does usually lead to excessive bulk and vague writing. Thanks for mentioning this point.
Brian: Glad to hear you like the bold formatting technique. By the way, I liked all the Montreal pics you posted on your blog.
Janet: You touched upon my number one pet peeve, actually. I put lack of modularity (what I call it) at the top of my list on an earlier post.
I use italics for referring to items in the GUI and bold to sometimes emphasise a word, such as ‘not’ in a warning to users.
As far as simplicity is concerned, why oh why do so many tech writers insist on clogging up their text with geek-speak?
Think about it. Do your users really care whether a menu pulls down, pops up or for that matter that ‘Print’ is a button? No, of course they don’t.
Less is more!
Replace wordy waffle such as this:
Click the “File” pulldown menu, click “Save,” and click “PDF.”
with:
Click File > Save > PDF.
[imagine File, Save, and PDF in italics]
[...] Rather Be Writing: If you’ve got a technical post coming up, you really need to read this post from Tom … Lorelle on WordPress: Lorelle reminisces about what she’d do differently [...]
In addition to the problem of not numbering steps, inexperienced writers often make an opposite mistake of numbering things that aren’t really steps.
For example:
1. Select the ABC option.
2. The ABC window opens.
3. Click your name.
4. Your profile opens.
#2 and 4 are not actions. They are result statements. This can confuse the reader.
Better to say:
1. Select the ABC option.
The ABC window opens.
Etc.
Or even better:
1. Select the ABC option.
2. On the ABC window, click your name.
I think the use of quote marks is a hangover from the old days of typewriters when there was no way to format text other than to underline it or put it in quotes. (I’m talking about the days before the Selectric.)
A book I often give to people who are just beginning to use computers is _The PC is not a Typewriter_ by Robin Williams.
She introduces her readers to the joys of word processing.
Holly,
Thanks for the comment. Here’s a question for you — do you think the result statement after each step is necessary? Or does this add extra bulk to instructions? This is something I’ve debated lately. Do we really need a pattern like this:
action
result
action
result
action
result
That makes instructions twice as long.
I agree that it gets tedious to continually use results statements.
I don’t think they are a must. It really depends on the audience and the complexity of the application.
Tom, your list is detailed and accurate.
However, I would like to ask whether the mistakes that non-professional writers do find their place to any official deliverable.
As far as I know, it does not. It is common to find such mistakes at Functional Specs written by novice product managers, for example. But these non-professional writers write to audience within the company (some of them could be professinal writers). In addition, turning into not-so-novice PMs, they learn to write more professionally. Most of the non-professional writers I know can handle a document with 4-6 styles (Normal, 3 Headers, Bullet, Number and Comment). This is enough. If a document has to be delivered – for example, an installation manual – then the writer who copies it into the official company temple, could spend a minute or two on formatting.
I would like to think that the writer’s role is to write. To write accurately, concisely and purposefully. formatting a document, PDFing it, etc, is only a bonus.
Hello Tom.
I agree with your point of need of writing action-result for each step. I use one solution when it becomes too much in a procedure – I try to put in the result in the next step itself, as in the following example.
Example of too many action-result, action-result, action result steps:
1. Select the ABC option. The ABC window opens.
2. Click your name.Your profile opens.
3. Click Edit. The Edit window opens.
Example of putting the result in the next step:
1. Select the ABC option.
2. In the ABC window,click your name.
3. Click Edit to modify your profile details.
The action-result seems to be a good approach. It’s good to try methods on non-computer procedures.
To be a productive citizen:
1. Work. You are taxed.
2. Work. You are taxed.
3. Work. You are taxed.
4. Death. You are taxed.
5. Rest in peace. Your family is taxed.
Perhaps this is how the Terminator would view it:
(action+result)^n+1
I guess the only question* that remains is:
- What would Bryan Boitano do?
*Disclosure: I am currently writing a working title “Death, taxes, and what Bryan Boitano would do.”
Tom, this is a great post. I am not a technical writer but I often have to explain technical-esque processes to my clients. I am often explaining how to navigate a control panel, purchase steps for domains, SSL, etc. These tips will really come in handy the next time I have to do that.
Thanks for stopping by my blog as well! I’ve got a little work to do over there. You can count on seeing a post about this post in the near future.
[...] Click Here to Read The Article [...]
[...] Three Simple Mistakes Non-Technical Writers Make Article on mistakes of non-technical writers on the Technical communication blog [...]
I also find that the use of Bold for commands is very effective. I also ensure that bolded commands are set in “small caps” to make it easy. I think that tech writers should stick to Plain English when writing out instructions. I publish most documents in two languages — a headache in itself — Now if the French translators could learn Plain French, it would certainly make my day; I hate having one document that clocks in at 20-30% more text!