Writing Technical Documentation and User Manualsby
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.
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.
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.
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.
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.
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|
| Reporting Bugs|
| 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."
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.