Writing Technical Documentation and User Manuals by Walt Stoneburner

v0.2

---

Who Is Your Audience Is it you? Notes. Is it someone who's intimately familiar with the product? Reference sheet. Is it a programmer? Technical documentation. Is it a novice? Clear and explicit instructions with illustrations.

Know Thy Audience

On the surface, the problem with writing decent documentation is not knowing the intended audience; you need to think as they think, walk in their shoes, and use terminology, concepts, and analogies they are already familiar with.

But the real problem eventually lies in the fact that the audience you think you have is not the one you really have. And to makes things worse, audiences change with time. People learn. The new user eventually becomes a power user.

Take for example a software library, generically the marketing literature must convince upper management to buy it, it should let system administrators know how to install and configure it, at a high level it should let the architects know what it can do and how the pieces fit together, at a lower level it should teach a developer how to use it, and at the lowest level it should explain the nitty-gritty to the hardcore techie.

Just as documentation is designed for people have varing degrees of personal experience, there's also a dimension of usage pertaining to roles and tasks. Tasks may be partitioned among different people. Thus, the office flunkie will need detailed steps for knowing how to install this new package and validate he installed it correctly. The user guide will need to be explanatory. The reference guide can focus on details. Different audiences and different tasks require different levels of details.

A good way of looking at the problem is that you have to address at least two kinds of people. Those who want to tell their computer what to do (power users), and those who want their computer to tell them what to do.

Example Manuals

Document of Documents Explains what documents are available, what's in them, and where to find them. README Explains what the software does and which documents/manuals you should check out. It should also contain contact information for the company and/or author, tell where the primary distribution point, and always list the version details. COPYRIGHT Copyright and license information. LICENSE Full license agreemnt. MANIFEST Explains what was delivered on the media and in the box. Helps validate product completeness. AUTHOR Explains how to contact the author through snail mail, email, fax, and phone. Provides their home page and optionally a bio. CREDITS Lists the contributions to the project made by various people. FAQ Frequently Asked Questions. This is your support-desk in a file. Every question you get repeatedly asked should be documented here so that you don't get asked again. It's important to organize it well so that people actually use this resource. INSTALL Installation and Upgrade instructions. The Quick Start section should be brief and assume the user has experience installing products before. The Detailed Installation section should explain each step assuming the user is a novice and is running into problems. Ideally there should be a Validation section which lets the user know how to check the system to see if everything was installed properly. User Manual Assumes the user knows nothing about the software, other than a high level impression of what it might do. Explains what the package does and how to use it. It explains abbreviations and expresses ideas in simple terms. Reference Guide Assumes the user has used the software before. Helps him find a specific option, command, syntax, feature, or explain a behavior. Programmers Guide Explains the product in terms and examples suitable for a software developer to understand how it works, extend its capabilities, interoperate with it, or make code contributions.

Those Old Friends

Your documents should always answer who, what, when, where, why, and how. The context of those question changes based upon the manual written.

Organization

The fact of the matter is that people don't like to read documentation. Few ever will. Have a definite starting place, a "document of documents."

Reading help is a last resort. Users want to try things out for themselves first and only when the situation crashes'n'burns will they make the effort.

That means that you can't count on things being in a pristine state when explaining an example. If you're writing a tutorial, show them how to get back to square one so they can follow along.

Supply a Table of Contents, supply an Index, use footnotes for clarifications and external sources, and by all means Cross-Reference between sections and other manuals. Documentation delivered with a product should be treated holistically and not as a treasure hunt.

If you can avoid making the user flip to other sections to find a required piece of information, do so, even if at the expense of redundancy. To get more related information is okay, but not mandatory information. Express dependencies if there are any.

One of the most frustrating aspects of learning an Object Oriented Library is trying to find out which methods are available and which one should be called when. Documenting just the methods implemented by a given class is great reference for an implementor, however it is a hardship for the user of the class.

Another example; assume a system that performs an action and then emits a message. Putting yourself in the roll of QA, think how one might test the system by provoking it to produce a given specific message. The documentation needs to answer both "what message(s) are produced by this action" and "what action(s) produce this message?" One question is at the producer section of the manual, the other is in the consumer, or put another way, one reader is trying to get the system to do something, the other is trying to find out why the system did something.

Some systems, especially those capable of internationalization, will store codes in one table, corresponding messages in another, and sometimes acceptable values and other business rules in another. This is great for architects, but a strain on implementors, QA, and end users who get the information unified. Provide information as the end user sees it, don't make people read multiple points of the documentation concurrently to get full understanding.

If your system is capable of communicating its operational state, it should be documented.

Errors

When reporting an error number or message, make sure the error message is clear. Error codes are for computers, error messages are for people.

It's not good enough to explain what is wrong, because the user wants to know why they are seeing the error and what they must do to resolve it or investigate further.

Tell them.

Distribution Formats

Keep it simple.

While info provides a nice hyper-text view of the world, it doesn't work well when emacs isn't around.

HTML is a fairly universal format, but if you don't have a GUI browser, or even a text based one like lynx or links, then users not familiar with HTML syntax will have a hard time reading your pages, especially if they were auto generated and contain decorative markup.

man is almost always available on Unix systems, but if the admin doesn't have the MANPATH set correctly, the documentation might not be available. Even so, this is usually the first place on the system people look for assistance. When producing man page documentation, be sure to include as many sections as are relevant:

• Name	• Configuation	• Environment Variables
• Synopsis	• Defaults	• Signals
• Description	• File Formats	• Options
• Arguments	• Footnotes	• Diagnostics
• Example(s)	• API Functions	• Extended Diagnostics
• Caveats	• Return Value(s)	• Warnings
• Bugs	• Macros	• Errors
• File(s)	• Actions	• Notes
• Miscellaneous	• Addendum	• Conforming To
• Security Notes	• Hints
• Source	• Deficiencies
• History	• Manuals
• Mailing List	• URLs
• Author(s)
• Reporting Bugs
• License
• Copying
• See Also
• Disclaimer	Items in the left column are more common than those towards the right.

 

Adobe's PDF format has quickly become a standard, but not everyone has a viewer installed. It's quite possible the user isn't at a graphics terminal.

Microsoft's DOC format keeps changing; still not everyone will have the most recent version of Word or some tool to decode it.

Although postscript generate beautiful content, not everyone has a PostScript capable printer or, if they do, knows how to get the raw PostScript to it. Yes, there are applications like ghostview which render postscript, but that assumes the software is there, the user knows about it, and a graphic terminal is available.

Many OpenSource projects come with documentation in LaTeX (or TeX) format so that users can generate any format they want. This works great for power users, but novice users aren't going to know how to do this and may not have TeX installed.

As such, the safest course of action is produce plain text files that the user can view, print, or include with it a "pretty version."

Bound Documentation

Most people prefer printed documentation when they are reading. It's easier to write on, mark your place in, and take to places where there isn't a computer.

Documentation that forces users to alternate attention between the printed page and the computer should lay flat without requiring a paperweight. There are a number of binding methods available to achive this.

Electronic documentation has the advantage that it's searchable. A good index and proper cross-reference mechanism will handle most of the cases.

If you're going to provide documentation in printed form, be kind and provide an electronic copy as well.