Writing Techincal Documentation and User Manuals by Walt Stoneburner

v0.1

---

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 face that the audience you think you have is not the one you really have. And to makes things worse,your audience changes.

Take for example a software library, generically the literature must convince upper management to buy 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.

Recognize that while just as there's a difference experience level, there's also a different tasks documentation is used for. Tasks may be partitioned to 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.

A good way of looking at the problem is that you have to address 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. 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 an option, command, syntax, feature, or explain a behavior. Programmers Guide Explains the product in terms and examples suitable for a software developer.

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, they want to try things out for themselves first and only when the situation crashes'n'burns will they make the effort.

Have a definate starting place, a "document of documents."

That means that you can't count on things being in a pristine state when you explain 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.

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. Documenting just the methods implemented by a given class is great for an implementor, however it is a hardship for the user of the class.

Additionally, suppose you have a system that takes an action and emits a message. Now, put yourself in the roll of QA; you want to test the system by provoking it to produce a given message. Your documentation should 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.

Another case is where you might have to construct a message of various types, however the type codes and acceptable values are located somewhere else. This is great for architects, but a strain on implementors. Provide both.

Errors

If you're going to report an error number or message, make sure the error message is clear.

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

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 fluff.

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 is quickly becoming 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.

One solution is to provide postscript documentation, the problem is not everyone has a PostScript capable printer or 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. Again, 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 import along with 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 where users must 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.