Practical .NET

Writing User Manuals: Get Someone Else To Do It (Seriously!)

Just because you've created an application, it may not need a user manual, guide or help system. And, even when your application does need that kind of support, you should -- at all costs -- avoid writing it.

• By Peter Vogel
• 12/05/2013

Since I've been having such good luck discussing the value of not commenting code, I might as well wade into another contentious area: end user documentation. However, this discussion is almost certainly completely redundant for the following two reasons:

1. It's unnecessary
2. If it is necessary, someone else should do it

You May Not Need a User Guide
Many (most?) in-house business applications are released without any user documentation, such as a manual, a user guide or help system. But that shouldn't necessarily be thought of as a failure. In many cases, creating a user manual for in-house business applications is a waste of time.

If some users have been involved in the application development process (requirements analysis, user interface design and acceptance testing, among other tasks), those users probably have a "good enough" understanding of the application to get by. We'll call those users "application experts." With a reasonably well-designed UI (a UI where a user knowledgeable about the business task always knows what to do next), those experts, coupled with occasional access to the developers supporting the application, can support the rest of the user community. Effectively, the experts provide just-in-time training to the rest of the user community, at least for the near term. This does assume a user community that communicates with each other and isn't so volatile that the experts are replaced before they have a chance to pass on their knowledge.

This only works in the near term, however. In the long term, the results from this process degrade. As experts move on, they must pass their expertise to the next generation of experts. Some loss and distortion of information always takes place. By the third generation of "experts" (i.e., the people who replaced the people who were present at the creation), much of the knowledge about the system will have become superstitious ("If you do it this way, it works") rather than informed ("Do it this way because..."). Therefore, "long term" means the time it takes to replace the experts twice. If that's longer than the life of your system, then you don't have a problem.

And it may not even be a problem if the understanding of the application descends to superstitious behaviour. The key here is whether the users are performing the same activities over and over again. If so, a superstitious understanding of the application will probably be good enough. However, in an environment where users have to face problems they haven't seen before, superstitious behaviour won't be sufficient and users will need to understand how the system works.

Assuming that none of the scenarios described above apply (the application development process doesn't generate application experts in the user community; users don't communicate with each other; the lifespan of the experts is less than the expected lifespan of the application; superstitious behaviour isn't good enough), then some form of end user documentation is required. That doesn't mean it will be produced, of course, but if it is you should avoid taking on the job.

Why You Shouldn't Write It
If you're reading articles on this site, you're almost certainly an application developer. If so, you're also exactly the wrong person to write the user manual. Your inside knowledge of the application actually disqualifies you from being the right person to produce the documentation.

Let me begin by saying that it's a common misunderstanding that anyone can write a user manual. Do recognize that, as the author of a four-day course on technical writing (gratuitous plug), I have a vested interest in claiming that explaining things is hard -- my testimony is suspect. But I'll claim that most people don't even understand what the essential issues in technical writing are. For instance, most people assume that the most important part of explaining things is understanding whatever it is you want to explain. That's not even remotely true. The most important part of explaining things is understanding who you're explaining things to.

For instance, because of that misunderstanding, developers (when asked to write about their application) talk about how the application works and deploy all their knowledge about the internals of the application. You can see this approach to technical writing in action in much of the .NET documentation -- it seems aimed at someone who wants to recreate .NET. Of course, the audience for end user documentation is deeply uninterested in this information.

Understanding who you're explaining things to means understanding what end users care about, and end users don't want to know how the application works. What end users do want to know is how to get the application to support them doing their job. It's the difference between talking about "how it works" versus "how you use it" or "how to get it to do this."

For instance, one kind of documentation that developers tend to produce is the "annotated form": They take a screenshot of a form and obsessively describe what each item on the screen does. This is almost completely useless to the end user. The end user has some task to perform, which often crosses multiple forms. Even when a task is focussed on a single form, typical variations on the task require the user to access other forms. And, finally, in the rare case where a user does use only a single form, the user often only needs some part of it and must, in any case, use the components of a form in a specific order. The "annotated form" documentation doesn't even begin to address any of these needs. While developers think in terms of forms, end users think in terms of tasks or jobs.

What users need is "task-oriented" documentation that takes a task from the user's life and shows how the application supports that. The only person who actually understands the end users' tasks and life is another end user. This means that the only person who has even a chance at creating information that your users need is someone from your user community.

Don't let yourself be given a job that you can never succeed at. Get someone else to write the user manual.