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.

Extras
PETS
Extras
FOOD+DRINK
Extras
OUTDOOR+ACTIVITY
Extras
GADGETS+TECH
Have you tried new the Independent Digital Edition apps?
Extras
FASHION+BEAUTY
Extras
FOOD+DRINK
Extras
FASHION+BEAUTY
Extras
FOOD+DRINK
Extras
FASHION+BEAUTY
Extras
HOUSE+GARDEN
Extras
FASHION+BEAUTY
Extras
HOUSE+GARDEN
Extras
FASHION+BEAUTY
Extras
FASHION+BEAUTY
Latest stories from i100
Have you tried new the Independent Digital Edition apps?
SPONSORED FEATURES
Independent Dating
and  

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

Day In a Page

Giants Club: After wholesale butchery of Idi Amin's regime, Uganda’s giants flourish once again

Uganda's giants are flourishing once again

After the wholesale butchery of Idi Amin's regime, elephant populations are finally recovering
The London: After 350 years, the riddle of Britain's exploding fleet is finally solved

After 350 years, the riddle of Britain's exploding fleet is finally solved

Archaeologists will recover a crucial item from the wreck of the London which could help shed more light on what happened in the vessel's final seconds
Airbus has patented a jet that could fly from London to New York in one hour

Airbus has patented a jet that could fly from London to New York in one hour

The invention involves turbojets and ramjets - a type of jet engine - and a rocket motor
10 best sun creams for kids

10 best sun creams for kids

Protect delicate and sensitive skin with products specially formulated for little ones
Tate Sensorium: New exhibition at Tate Britain invites art lovers to taste, smell and hear art

Tate Sensorium

New exhibition at Tate Britain invites art lovers to taste, smell and hear art
Ashes 2015: Nice guy Steven Finn is making up for lost time – and quickly

Nice guy Finn is making up for lost time – and quickly

He was man-of-the-match in the third Test following his recall to the England side
Ashes 2015: Remember Ashton Agar? The No 11 that nearly toppled England

Remember Ashton Agar?

The No 11 that nearly toppled England
Turkey-Kurdish conflict: Obama's deal with Ankara is a betrayal of Syrian Kurds and may not even weaken Isis

US betrayal of old ally brings limited reward

Since the accord, the Turks have only waged war on Kurds while no US bomber has used Incirlik airbase, says Patrick Cockburn
VIPs gather for opening of second Suez Canal - but doubts linger over security

'A gift from Egypt to the rest of the world'

VIPs gather for opening of second Suez Canal - but is it really needed?
Jeremy Corbyn dresses abysmally. That's a great thing because it's genuine

Jeremy Corbyn dresses abysmally. That's a great thing because it's genuine

Fashion editor, Alexander Fury, applauds a man who clearly has more important things on his mind
The male menopause and intimations of mortality

Aches, pains and an inkling of mortality

So the male menopause is real, they say, but what would the Victorians, 'old' at 30, think of that, asks DJ Taylor
Man Booker Prize 2015: Anna Smaill - How can I possibly be on the list with these writers I have idolised?

'How can I possibly be on the list with these writers I have idolised?'

Man Booker Prize nominee Anna Smaill on the rise of Kiwi lit
Bettany Hughes interview: The historian on how Socrates would have solved Greece's problems

Bettany Hughes interview

The historian on how Socrates would have solved Greece's problems
Art of the state: Pyongyang propaganda posters to be exhibited in China

Art of the state

Pyongyang propaganda posters to be exhibited in China
Mildreds and Vanilla Black have given vegetarian food a makeover in new cookbooks

Vegetarian food gets a makeover

Long-time vegetarian Holly Williams tries to recreate some of the inventive recipes in Mildreds and Vanilla Black's new cookbooks