Plea to Programmers and Instruction Manual Writers.

Instructions: Open packet, Eat nuts.

On an  American Airlines packet of nuts.

Rather silly, because everybody knows this.  However, the main problem with the above is not that it is silly but that the writer has missed the most important part of the instructions, which is “How to open the packet”.

How many times have you seen crisps or peanuts flying in all directions, due to people struggling to open a packet.

I would imagine that a good proportion of the time spent by clean-up crews, is finding and removing peanuts and crisps from inaccessible places on the aircraft. This means that many $1,000s are wasted each year, and probably a few tons of peanuts and crisps are wasted.

All because of incompetent instructions.

The same type of silliness is endemic in the computer industry. From the classic Microsoft silliness of having to press the ‘Start’ button to ‘Stop’ the the computer, to far more serious lapses of intelligence that costs $millions every year.

Too many ‘technical writers’ assume that the reader knows as much about the subject as they do. Obviously this is silly, because if they did they wouldn’t need to read the instructions. As an engineer I have spent a lot of time over the years writing instructing manuals for all types of equipment.

Very early on in my career I determined that any instructions that I wrote should be understandable by my grandmother.  (Not literally as both my grandmothers died before I started work.)

Tips on writing instructions.

1. Know what you are writing about.
2. Assume that your reader does not know anything about handling or using the equipment or system.
3. Do not use abbreviations for anything unless there is clear information on the same page to explain the meaning.
4. Avoid using obscure (to the public) technical terms, it may seem clever to you but it brands you as a lousy technical writer.
5. Try and stay with a common vocabulary. Almost anything can be explained by using less than 500 commonly known words in any language.
6. None of the above mean that you have to treat the readers as idiots. That fact that you can’t understand your wife’s knitting pattern does not mean that you are an idiot. Give the same consideration to your readers.

Most computer related instruction manuals  contain parts that are mostly ‘gobbledegook’ ( a word or series of words that are meaningless) to the reader . Get your grand mother to check all your work for gobbledegook, because you won’t be able to recognize it yourself. Someone at the next desk to you may understand what you are trying to say, but real people won’t.

As a good guide to technical writing you should read the computer technical guides by David Welsh Pogue. A master at his subjects and a super sense of humour. No, he is not paying me for saying that, I just think he is the best technical writer on computers I have read, and it is pertinent to this posting. Just borrow one from the library to read irrespective of your particular computer preference.

********************************************************************

Many years ago I was urgently requested to handle the technical information department of a wire and cable making machinery company. The first few weeks were very hectic because they were months behind in their delivery of instruction manuals, and I was unfamiliar with the machinery. After about 6 weeks I started to get involved with the engineering departments to get familiar with the equipment, and to study the “standard” sections of the manuals that I had been sending out. I found that I could not reconcile the information in these “Standard” sections with what I had learned in the engineering and manufacturing departments.

I then had a meeting with the companies commissioning engineers to discuss my problems. I found that they could not make sense of the “standard” documentation either. Checking up later I found that some of these inaccurate “standard” documents had been issued over a period of 10 years without anyone, even clients, complaining about them.

Over the next few weeks I had to rewrite all the standard sections, and create graphics where I thought necessary.

It is clear therefore, that because no-one had complained over a period of 10 years,  nothing had been done about the problem.  $1000s must have been wasted over this 10 year period due to people having to work out for themselves how to operate equipment. Another problem here is that if people cannot understand a particular set of instructions, they tend to consider that it is their fault for being stupid.  In almost all cases it means that the writer of the instructions was incompetent.

How many times have you read the following or similar, in computer operating manuals, ” It is better if you spend a little time playing about with your computer”. Generally this means that the writer himself is totally confused and would rather you worked it out for yourself.

********************************************************************

A further problem I discovered was with translations. Translating technical subjects is full of pitfalls for the unwary. Is it a bolt or a set-screw? Is it a cog or a sprocket?  Having the correct definition makes it more likely that the translation will be correct. Sometimes it may be necessary to supply photographs or diagrams with the English text to enable the translator to supply the correct words.

In many cases I found it necessary to produce separate “Translatable English ” versions of operating instructions.

—————————————————

From the WordPress Help Pages.

“If none of this make sense and you have someone to administrate your system for you, show the above to them and they should be able to figure it out.”

Maybe!!!!!!!!!! And what if I don’t?

WordPress writers do have an excuse, because they write these from the goodness of their hearts, and most of them have other jobs to do.

——————————————–

If you find words in my web site that do not appear to be be sensible in none-English languages, please send information and I will try to re-word it.

Author – Brian Williams