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
ARTS+BOOKS
New Articles
Beauty subscription boxes, glossy box
BEAUTY
Extras
TECH
Extras
FASHION
PROMOTED VIDEO
Have you tried new the Independent Digital Edition apps?
Extras
GADGETS
Extras
BEAUTY
New Articles
HOME
Extras
GADGETS
Extras
BEAUTY
Extras
HOME+GARDEN
Extras
FASHION
Extras
OUTDOOR & ACTIVITY
Extras
OUTDOOR & ACTIVITY
Extras
DRINK
Latest stories from i100
Have you tried new the Independent Digital Edition apps?
Independent Dating
and  

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

Day In a Page

Syria crisis: Celebrities call on David Cameron to take more refugees as one young mother tells of torture by Assad regime

Celebrities call on David Cameron to take more Syrian refugees

One young mother tells of torture by Assad regime
The enemy within: People who hear voices in their heads are being encouraged to talk back – with promising results

The enemy within

People who hear voices in their heads are being encouraged to talk back
'In Auschwitz you got used to anything'

'In Auschwitz you got used to anything'

Survivors of the Nazi concentration camp remember its horror, 70 years on
Autumn/winter menswear 2015: The uniforms that make up modern life come to the fore

Autumn/winter menswear 2015

The uniforms that make up modern life come to the fore
'I'm gay, and plan to fight military homophobia'

'I'm gay, and plan to fight military homophobia'

Army general planning to come out
Iraq invasion 2003: The bloody warnings six wise men gave to Tony Blair as he prepared to launch poorly planned campaign

What the six wise men told Tony Blair

Months before the invasion of Iraq in 2003, experts sought to warn the PM about his plans. Here, four of them recall that day
25 years of The Independent on Sunday: The stories, the writers and the changes over the last quarter of a century

25 years of The Independent on Sunday

The stories, the writers and the changes over the last quarter of a century
Homeless Veterans appeal: 'Really caring is a dangerous emotion in this kind of work'

Homeless Veterans appeal

As head of The Soldiers' Charity, Martin Rutledge has to temper compassion with realism. He tells Chris Green how his Army career prepared him
Wu-Tang Clan and The Sexual Objects offer fans a chance to own the only copies of their latest albums

Smash hit go under the hammer

It's nice to pick up a new record once in a while, but the purchasers of two latest releases can go a step further - by buying the only copy
Geeks who rocked the world: Documentary looks back at origins of the computer-games industry

The geeks who rocked the world

A new documentary looks back at origins of the computer-games industry
Belle & Sebastian interview: Stuart Murdoch reveals how the band is taking a new direction

Belle & Sebastian is taking a new direction

Twenty years ago, Belle & Sebastian was a fey indie band from Glasgow. It still is – except today, as prime mover Stuart Murdoch admits, it has a global cult following, from Hollywood to South Korea
America: Land of the free, home of the political dynasty

America: Land of the free, home of the political dynasty

These days in the US things are pretty much stuck where they are, both in politics and society at large, says Rupert Cornwell
A graphic history of US civil rights – in comic book form

A graphic history of US civil rights – in comic book form

A veteran of the Fifties campaigns is inspiring a new generation of activists
Winston Churchill: the enigma of a British hero

Winston Churchill: the enigma of a British hero

A C Benson called him 'a horrid little fellow', George Orwell would have shot him, but what a giant he seems now, says DJ Taylor
Growing mussels: Precious freshwater shellfish are thriving in a unique green project

Growing mussels

Precious freshwater shellfish are thriving in a unique green project