Documentation Tips

I got into the documentation business after I saw how many "technical problems" and "people problems" were really documentation problems. I saw workers perceived as inept, when all they needed was a description of how to do their job. I saw wonderful computer programs perceived as terrible, until the users got paper and hypertext documents explaining how the program was designed to be used. I saw maintenance programmers trash well behaved applications because they had no clue as to the original programmer's intent and design. If your employees do not have the time or ability to document processes under their control or design, hire someone from the outside. Here are some tips I find useful:

A document has thirty seconds to impress a user

If it doesn't impress, it's thrown in the drawer. It must have an attractive cover. If it's long enough to have a table of contents, the table must be attractive and accurate. All text and graphics must be designed to reproduce well, and the document must be reproduced on good equipment. Hypertext documents, especially the contents page or home page, must look good at any resolution.

Reduce the intimidation factor. Make the manual as short as possible. Use the 80/20 rule to best advantage. Use HUGE amounts of white space between paragraphs and in the margins. Use only two levels of subheading below each chapter. A third, and possibly even a fourth, subheading level is acceptable if used sparingly and only where its absense would jeopardize the clarity of the document. Each subheading level should have a clear, consistant and standard format.

[ Top of page | Troubleshooters.Com | Home page | Email Steve Litt ]

Tailor the document for the intended audience

To be useful for the intended audience, a document must contain the right information, and be read and understood by that audience. Below are some standard document types for various audiences:

Docmentation survey
Intended for management. Lists existing documentation and where to find it. May contain suggestions for document managment. Provides top level list of systems and their major components. Outlines which areas are in jeopardy without further documentation, which types and formats of documentation are necessary, and a cost estimate.

Quickstart guide
Intended for the user who won't read the manual. Contains only the instructions for the most common operations, and warnings against the most fatal mistakes. This is the least intimidating of all documentation. The theory is that a little information is better than none (if the user declines to read a more thorough document).

User guide
Intended for the user who wants to know what he/she is doing, and how to do it better. Contains instructions for most operations, and all appropriate warnings. It may contain some easy to understand theory. It may contain troubleshooting information for the most common user addressable problems.

Maintenance manual
Addresses the needs of the person configuring or troubleshooting the system. Contains extensive troubleshooting information, and explanation of configuration options. Contains description of user-visible system components. May contain block diagrams or schematics if troubleshooter needs to make physical repairs.

Internals manual
Intended for the person needing to modify or add to the system. Contains the original design philosophy, reasons and priorities for design choices, block diagrams, schematics, and special design tricks and tips used in the system. Also contains detailed change history complete with their design choice priorities.

Online help
Hypertext document used by the end-user while accessing the program. Contains context-sensitive information relating to the window the user is in. Requires tight coordination between the tech writer and software developers.

[ Top of page | Troubleshooters.Com | Home page | Email Steve Litt ]

From the start, be ready for your documentation to go hypertext

A surprising amount of documentation goes on-line today. On-line documentation avoids printing costs, delays and mistakes. It eliminates print overruns and disposal costs. If properly placed, one copy of the document can be made available to the enterprise or group. This makes the document easy to find and eliminates the possibility of reading an out-of-date version.

Documentation should always be styles based for consistancy and (relatively) easy conversion to hypertext. Most modern Winhelp authoring tools work with MS Word, so that's the preferred word-processor for docs likely to go on-line.

Styles based HTML editors are now available. For instance, I did Troubleshooters.Com in Microsoft FrontPage, a styles based HTML authoring tool. HTML editors have come a long way since July, 1995, when I used NOTEPAD to create the this (Litt's Tips) website.

[ Top of page | Troubleshooters.Com | Home page | Email Steve Litt ]