Computers: How-to-do-it of manuals: John Watson laments the way most computer guides are written

COMPUTER manuals are dreadful for the same reasons that so much else is dreadful: fear, greed, pride, arrogance, ignorance, stupidity. Believe me: I have written several of the things.

People who buy a computer program have an irritating habit of wanting to know how to use it. The natural response of the inconvenienced software company which has written the program is to produce a manual that tells people what the program does - which is not the same thing at all. So you end up with manuals that tell you that if you press a certain key the program will go shanga-langa-bang and that if you press another key it will go shuffle-shuffle-boom.

Users do not want to know what the program does, they want to know what they can do with the program and how to do it. Only the weird, the bored, or the competition ever ask themselves 'I wonder if the program can . . .?' Whereas millions of users every day ask themselves 'I wonder if I can . . .?'

This problem is compounded because different kinds of people write manuals. They may be written by the company that produced the program, often by a programmer. When the manuals are written in-house, Shaw's dictum that 'all professions are conspiracies against the laity' comes true in trumps.

I have taught computer skills to absolute beginners as well as working among programmers whose minds make particle accelerators look sluggish. I am miserably aware of the huge gulf between the communications software programmer who eats electronic transmission protocols for breakfast and the textile designer who turns his or her machine off in despair because he or she does not know if it has something described as a C: drive.

In-house writers can never fully put themselves in the place of the beginner - not after their A-level maths, three years of computer science and years working for a software company. Their prediliction for telling the user what the program does, the unexplained jargon used, the wild guessing at the level of the user's prior knowledge, the material that is omitted-assumed-known, will all lead to an incomprehensible manual. Getting an in-house programmer to write the manual is like asking Ayrton Senna to give driving lessons.

The alternative is imported writers. They can at least arrive in some ignorance of the product to mirror the position of the first-time user, but as the craft becomes increasingly specialised, the imported writer will be required to know almost as much as the programmers and so the professional conspiracy continues.

The next problem is caused by the haste with which software is published, in a competitive industry. Often, a program is sold when marketing says it should be, before it has been fully tested and before the manual has been tested at all. This means that the manual has had to be written as the software is being developed.

I have sat across the desk scribbling notes from a programmer deciding how a section will operate. He changes his mind; I revise the notes. He changes his mind again; I re-revise the notes. After that has happened several times it is only hope that supports what goes on to the page, not certainty.

The impenetrable design of many manuals is also a result of the program-oriented, as opposed to the user-oriented, approach.

Who ever sat down with relish to read 50 pages of a computer manual? What happens in real life is that the user has an idea, wants to know if the program will allow it, picks up the manual with some effort and turns to the index, only to discover that what the user wants to know is not apparently worth including.

The index should be the soul of the manual. In my ideal world, the index would take up around a third of the manual. Every word that the program throws on to the screen would be in there, as well as every conceivable synonym and alternative form of words to describe every possible action that the user might imagine doing with the program.

And having quickly and successfully found a page reference to printing diagonal columns on a landscape format - which has entries under p, d, c, l, and f - the user turns to the page and finds numbered, single-step instructions in English on how to do it - no matter how many steps it takes or how simply the steps are explained - no one ever complained about being told too much.

Apart from the index and the single-step sections, I would allow a short introductory section broadly describing what the program does - but that is all - no more than a few pages.

When teaching, I make a point of telling people that if they do not understand something it is only because it has not been explained to them properly - either by me or by the documentation. The relief on their faces is marvellous. So many people feel that this new technology is designed to make fools of them. And as long as software companies treat writing manuals as a costly afterthought, this is likely to continue.

Indybest Rain Jackets
Have you tried new the Independent Digital Edition apps?
Prosecco picture
10 best clutch bags
Latest stories from i100
Have you tried new the Independent Digital Edition apps?
Independent Dating

By clicking 'Search' you
are agreeing to our
Terms of Use.

Day In a Page

How could three tourists have been battered within an inch of their lives by a burglar in a plush London hotel?

A crime that reveals London's dark heart

How could three tourists have been battered within an inch of their lives by a burglar in a plush London hotel?
Meet 'Porridge' and 'Vampire': Chinese state TV is offering advice for citizens picking a Western moniker

Lost in translation: Western monikers

Chinese state TV is offering advice for citizens picking a Western moniker. Simon Usborne, who met a 'Porridge' and a 'Vampire' while in China, can see the problem
Handy hacks that make life easier: New book reveals how to rid your inbox of spam, protect your passwords and amplify your iPhone

Handy hacks that make life easier

New book reveals how to rid your email inbox of spam, protect your passwords and amplify your iPhone with a loo-roll
KidZania lets children try their hands at being a firefighter, doctor or factory worker for the day

KidZania: It's a small world

The new 'educational entertainment experience' in London's Shepherd's Bush will allow children to try out the jobs that are usually undertaken by adults, including firefighter, doctor or factory worker
Renée Zellweger's real crime has been to age in an industry that prizes women's youth over humanity

'Renée Zellweger's real crime was to age'

The actress's altered appearance raised eyebrows at Elle's Women in Hollywood awards on Monday
From Cinderella to The Jungle Book, Disney plans live-action remakes of animated classics

Disney plans live-action remakes of animated classics

From Cinderella to The Jungle Book, Patrick Grafton-Green wonders if they can ever recapture the old magic
Thousands of teenagers to visit battlefields of the First World War in new Government scheme

Pupils to visit First World War battlefields

A new Government scheme aims to bring the the horrors of the conflict to life over the next five years
The 10 best smartphone accessories

Make the most of your mobile: 10 best smartphone accessories

Try these add-ons for everything from secret charging to making sure you never lose your keys again
Mario Balotelli substituted at half-time against Real Madrid: Was this shirt swapping the real reason?

Liverpool v Real Madrid

Mario Balotelli substituted at half-time. Was shirt swapping the real reason?
West Indies tour of India: Hurricane set to sweep Windies into the shadows

Hurricane set to sweep Windies into the shadows

Decision to pull out of India tour leaves the WICB fighting for its existence with an off-field storm building
Indiana serial killer? Man arrested for murdering teenage prostitute confesses to six other murders - and police fear there could be many more

A new American serial killer?

Police fear man arrested for murder of teen prostitute could be responsible for killing spree dating back 20 years
Sweetie, the fake 10-year-old girl designed to catch online predators, claims her first scalp

Sting to trap paedophiles may not carry weight in UK courts

Computer image of ‘Sweetie’ represented entrapment, experts say
Fukushima nuclear crisis: Evacuees still stuck in cramped emergency housing three years on - and may never return home

Return to Fukushima – a land they will never call home again

Evacuees still stuck in cramped emergency housing three years on from nuclear disaster
Wildlife Photographer of the Year: Intimate image of resting lions claims top prize

Wildlife Photographer of the Year

Intimate image of resting lions claims top prize
Online petitions: Sign here to change the world

Want to change the world? Just sign here

The proliferation of online petitions allows us to register our protests at the touch of a button. But do they change anything?