User Manual

One of the most common myths about technical documentation is that nobody reads it. Let’s talk about this myth and four big reasons why you shouldn’t believe it.

Most of us can’t honestly say that we learned how to use a television or computer by studying a reference manual. And the Internet — that didn’t come with a user manual, either. So it’s worth asking: who actually reads user manuals?

First, let’s suppose that computer software or hardware ideally ought to be so well designed that users do not need to consult the online help or printed manuals.

This is not an argument for laying off technical writers, but for involving them earlier in the design process whenever possible as advocates for an excellent user experience. Too often technical writers are only hired after software design is done, so that they have less of an opportunity to improve the products.

It is also worth pointing out that reality falls well short of this ideal, especially when dealing with new and innovative products. As much as we would wish it, technology products are rarely self-documenting. They may seem that way to their designers and developers, but only because over familiarity produces a sort of spell on them.

Second, consider that users have limited attention span, and studies have shown that many website visitors only skim rather than read text. This is only an argument for writing help topics in a short and direct style. This is not an argument that “nobody reads documentation anymore”!

Studies that seem to claim that website visitors don’t read are talking about advertising-driven stories, not online help. There is no good reason to think that users who won’t read lengthy documents created by the marketing department won’t read online help articles when they have a specific product issue to solve.

Third, let us just acknowledge that some people do, in fact, read technical documents because it is simply their preferred form of learning. Not everyone learns in the same way, naturally. The fact that documentation is being consumed is quite evident from website traffic logs, feedback form inputs, and other user interactions.

Technical writers know our documents get read because users get in touch with us to praise or find flaws in the online help, and they sometimes call customer service centers after not finding what they need in the documentation. So, before anyone decides that there is no point in having a help system or user guide, we need to ask whether we are willing to sacrifice having a relationship with the many users who commonly refer to documentation.

Fourth, no one should confuse the fact that people do not constantly consult user manuals with the fact that they do not want to have one. Many users feel comfortable exploring a new hardware or software product by “playing around with it” precisely because they know that there is a safety net in the form of customer support (user manuals, online help, knowledge-bases, telephone support, etc.).

Therefore, at the very least, the claim that no one reads documentation is greatly exaggerated. It is commonly the case that users consult documentation when they need to perform a specific task and they have trouble. To get them out of their predicament, they need usable “how-to” documents.

There are many other important cases in which users need documentation: when they want to better understand the concepts behind an unfamiliar type of product or solution, when they ate learning how to perform a complex task for the first time, or when they need to look up a particular detail in a reference document.

Much the same point can be made about technical documents written for software engineers. Studies have shown that many computer programmers want to work with an API by studying the source code and its class declarations rather than consulting external documentation for the information they need. This sort of developer only consults the documentation when they encounter difficulties.

Even these sorts of developers can easily become frustrated if the only documentation provided is in the code. If code has complex method signatures or is auto-generated, it does not document itself. Recommended usage and best practices can not be conveyed by source code. Developers need a place to turn when the code isn’t enough, and that place is good documentation.

0 replies

Leave a Reply

Want to join the discussion?
Feel free to contribute!

Leave a Reply

Your email address will not be published. Required fields are marked *