Computers: How-to-do-it of manuals: John Watson laments the way most computer guides are written
Your support helps us to tell the story
From reproductive rights to climate change to Big Tech, The Independent is on the ground when the story is developing. Whether it's investigating the financials of Elon Musk's pro-Trump PAC or producing our latest documentary, 'The A Word', which shines a light on the American women fighting for reproductive rights, we know how important it is to parse out the facts from the messaging.
At such a critical moment in US history, we need reporters on the ground. Your donation allows us to keep sending journalists to speak to both sides of the story.
The Independent is trusted by Americans across the entire political spectrum. And unlike many other quality news outlets, we choose not to lock Americans out of our reporting and analysis with paywalls. We believe quality journalism should be available to everyone, paid for by those who can afford it.
Your support makes all the difference.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.