Mike Unwalla looks at what people want from software documentation.

'Nobody reads user manuals' and 'people always phone the helpdesk' are popular beliefs. Whether you agree or disagree, what is the evidence for your opinion?

At the Bransom User Group meeting in April 2007, TechScribe researched users' experiences of the software documentation that they receive. Using a questionnaire, we asked about their job roles, their documentation preferences, and their experiences of the existing user guide.

This summary presents our findings about user's preferences for software documentation. We obtained 29 responses from 64 attendees.

Bransom and its users

Bransom Retail Systems (www.bransom.co.uk) supplies computer systems to retail jewellers. Their jewellery stock management system is recommended by the National Association of Goldsmiths.

The software is used by a variety of customers, from small independent jewellers with only one or two shops through to well-known national chains.

Respondents covered many job roles: owner/director, sales manager, marketing manager, accounts manager, buyer, and administrative/clerical worker.

Preferred delivery format

More people preferred printed documentation than on-screen documentation (on-screen help), but surprisingly, most people had no preference. Perhaps what matters most to them is that the content answers their questions.

Preferred method of delivery:

Printed documentation 8
On-screen documentation 2
No preference 17
Don't read documentation 2

Method of finding information

Bransom prides itself on the helpdesk. Nearly half the respondents use the help desk in addition to using the documentation. 'It's easier to ring the helpline,' according to one respondent. Good documentation can reduce calls to a help desk, but it doesn't necessarily make sense to do so if the helpdesk is a selling point.

Bransom provides printable documentation in PDF format. We asked how people find information in a book. Respondents were asked to indicate all the methods that they use. Some people avoid documentation, so we included options to indicate this.

How people find information in a book:

Look at the contents page 16
Look at the index 13
Scan the book 3
Ask a colleague 7
Phone the helpdesk 9

Importance of background information

Two-thirds of respondents indicated that background information about a software product is important to them.

This indicates that documentation should include concepts of operation, explanations of overall workflows, and explanations of how the product relates to their business in general. Good design will ensure that people who have no interest can see that it's an optional extra for people who are interested.

The importance of background information about how a product works:

Not important 10
Important 19

Type of documentation

Nobody wanted reference documentation alone. However, nearly half the respondents thought that reference material was as useful as procedural information. Clearly, reference documentation fulfils a useful function.

Preferred type of documentation:

'How to' guide 16
Reference material 0
Both are equally useful 12
No response 1

Method of explanations

People learn in different ways. Received wisdom is that an individual typically has a specific preference. However, according the replies in this survey, most people prefer explanations that combine both words and pictures.

Preferences for visual or descriptive explanations:

Visuals 4
Descriptions 0
Visuals plus descriptions 22
No response 3


We make no claims to statistical validity for this small investigation; nevertheless, the results give guidance on what people want from user documentation.

Pleasing everyone all the time is not practical. However, if you know what your customers want, you will be able to provide suitable documentation that generally fulfils most people's needs.

Mike Unwalla (TechScribe) helps software companies to improve their user documentation. He designs user guides, manuals, and on-screen support systems.