Image: quality of apps

Improving software quality with user documents

Computer manuals are not good enough

Far too few computer users are satisfied with the documentation. It is often much too difficult to find out how to perform basic tasks.   How many of us have spent ages wrestling with finding out how to do something in Excel? Or tried to remove a page break in Word? Users spend far too much time trawling the web finding out how to do things. They shouldn’t have to. The software vendor should tell them. What does it say about you if your customers have to rely on the Internet to find out how to use your product?

How not to write manuals

Let’s look at an example. Some years back, the Visual C++ compiler was slow. It turned out that much of the time was taken generating something called a browser, so it was useful to turn off the browser. There was nothing in the documentation that told you how to do this. I seem to remember you had to select an entry on the options menu which presented a form with about six tabs. The form under one of these tabs had a button that opened another form. On this form there was a check box “Output browser” which you had to uncheck. The only way to find instructions for this was to follow the exact same path through the manual to be told “Check this box to output the browser”. Absolutely useless. By the time a user found the check box, it was obvious that’s what it did. What he needed to know was where to find the check box.

The user wants to know how to do something, how to carry out a job. Most manuals fail to tell him.

Here is another example. I play guitar and use a recording app called Cubase. Cubase is a powerful recording studio but using it is frustrating. The manuals contain lots of information about concepts like markers, hit points and audio parts, as well as highly technical terms, but don’t really explain what they are. They don’t explain what the concepts are for. There’s a very common recording task. A number of “takes” of a song are usually recorded. One take will be almost good but will have a mistake in a short passage. The recording engineer needs to access a take in which the mistake wasn’t made, copy the good section from that take and paste it into the target take. This is quite tricky and the manual doesn’t tell you how to do it.

What to do about it

The problem is that most manuals are written from the perspective of the computer, not the user. Also, far too many seem to be aimed at someone who already understands the application.

A major cause is that the authors are brought in far too late, usually after the software is written. There is some justification for this in that the manual clearly can’t be finalised until the software is complete. However, it can, and should be, planned much earlier.

Consider the project life cycle. Projects usually start with a specification of requirements. This is typically preceded by analysis or brainstorming to create a list of things users will want to do. When that is agreed, the software designers create a schedule of computer resources such as data tables, classes, modules and forms. When this is done, the user functions rarely map directly into the computer functions. Then the project moves into the programming phase. New data constraints emerge, needing tweaks to the design. This generates more changes to the functions. System testers design schedules of tests which are carried out.

All too often, that is when the technical author is called in. The author runs through the menu options and input forms. He writes a manual that describes what each box on every form does. It ends up stating the blindingly obvious.

The best way to write the manuals is to keep the initial list of requirements and for the author to use that as the start point. The requirement list provides the best index to the manual. The requirements of the systems tests can be another valuable input. The author should then interview the developers and find out where the user functions have been implemented.


Start the manuals from a list of user tasks and brief the author on these. Do not expect the author to work out what the application does. If you fail to brief him on this, you will end up with documents that are no help to a user.

Avoid stating the obvious. The whole point of user documents is to explain what is not obvious.

Use the FAQ forum. This will be tell you what questions the users ask. You really will end up with a better product if you revise your documents to answer these questions.

John McMillan

John McMillanJohn writes and talks on technology and advises companies on developing and marketing software products. He is the author of Kindle books How to write software for sale and How to market yout business. He has 30 year’s experience in the IT industry and has enabled several bodies to sell their knowledge through computer applications. He has been employed as a consultant by public bodies and by Cambridge and other universities.