Thomas Barker, in his book Writing Software Documentation, uses the term “the default manual” to describe a user’s guide that is organised according to features, rather than tasks. This sort of user’s guide has a chapter for each menu in a software program, and a section for each command. (For hardware, which Barker’s book doesn’t cover, it would describe every switch and button.) Barker rightly explains that this sort of manual is not really very useful for users. The information in a default manual, and in particular the way the information is organised, bears little or no resemblance to what the average user needs to do in their everyday working life. Like the old (and unfair) joke about Microsoft Customer Support, the information given is totally accurate but absolutely useless. In short, default manuals are the sort of things that give technical writing a bad name.

Like Barker, I believe in the importance of user focused documentation, and try never to write default manuals. Unfortunately a lot of my customers have yet to understand the difference between effective user assistance on the one hand, and the only kind of user manual they have ever been exposed to on the other, and the default manual is what they ask me to produce. I don’t always succeed in convincing them that their users deserve something better.

Barker does not discuss why default manuals are so prevalent. I can think of plenty of reasons. First of all default manuals appear to be quick and easy to write. They are based on the product’s features, so the structure of commands in user menus offers an instant structure for the manual, and an instant checklist to ensure that every thing is mentioned. Since they describe program features rather than user actions they are easy to write. Even the most junior programmer on the team knows that the New command on the File menu creates a new file. That’s why so many default manuals are indeed written by the most junior programmer on the team.

Default manuals reflect the developer’s world-view, or more accurately the development manager’s world-view. The development manager rarely sees any feedback or comments from customers, and has probably never spoken to a real life customer either. For development managers, thinking about users doesn’t just take time and effort, it requires a degree of objectivity and critical detachment from their work that was never part of their job descriptions. They have goals to achieve which are stated in terms of objects coded, features implemented, and overtime hours saved, not in terms of user task fulfilment or customer satisfaction. Those things have no relevance to their jobs or to their end-of-year bonuses.

The lure of the familiar is also significant. Like travellers’ tales of exotic creatures and peculiar peoples, the idea that a different and better way of writing user manuals might exist is regarded with more than a little scepticism by many in the developer community. Default manuals are all they have ever known.

A third reason for the popularity of default manuals is that they are an easy way of demonstrating that the development team’s “contractual obligations” have been met. I am thinking here of “contractual” in the broadest possible sense, and including not only written undertakings to external customers but also internal agreements and understandings with stakeholders within an organisation.

Default manuals are popular because they appear temptingly simple and easy, and because they can be shown to correlate directly to the product features. They can be written cheaply by an existing member of the team who won’t “bother” other developers with questions that waste their valuable time. Once they’ve been done, the development manager can tick several boxes at once – there is evidence that all the required features are there, the program’s features have been checked by a competent person, and hey presto, there are user manuals as well. In this scenario no-one is surprised or worried by the fact that the manuals will never be opened, let alone read. That was never anyone’s intention.

Fighting back against the default manual culture is a challenging and difficult undertaking, especially if you are the only professional writer around. But it is a noble cause and one that all technical writers should pledge themselves to.