Comments on: Three Simple Mistakes Non-Technical Writers Make

By: Lynn

Lynn — Thu, 12 Mar 2009 13:11:10 +0000

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!

By: ICTS - Technical Communications Newsletter (Vol. 3, No. 1)

ICTS - Technical Communications Newsletter (Vol. 3, No. 1) — Tue, 08 Jul 2008 12:28:32 +0000

[...] Three Simple Mistakes Non-Technical Writers Make Article on mistakes of non-technical writers on the Technical communication blog [...]

By: Three Simple Mistakes Non-Technical Writers Make » Trae Regan

Three Simple Mistakes Non-Technical Writers Make » Trae Regan — Thu, 16 Aug 2007 05:07:13 +0000

[...] Click Here to Read The Article [...]

By: Trae

Trae — Wed, 15 Aug 2007 15:12:44 +0000

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.

By: eldavo

eldavo — Tue, 07 Aug 2007 18:26:01 +0000

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.”

By: Meghashri

Meghashri — Mon, 06 Aug 2007 04:01:39 +0000

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.

By: avi

avi — Sun, 05 Aug 2007 08:34:22 +0000

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.

By: Holly

Holly — Sat, 04 Aug 2007 13:24:05 +0000

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.

By: Tom

Tom — Sat, 04 Aug 2007 11:43:22 +0000

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.

By: Holly Harkness

Holly Harkness — Fri, 03 Aug 2007 17:18:32 +0000

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.