Here's some advice from an experienced "how to" writer, who's also an experienced programmer, about how documentation should be structured to be useful.

Include an extended procedural tutorial. This section is for the user who doesn't have enough prior experience with similar products to guess what to do next. Don't mix tips about advanced tricks into this section, or cautions about product limitations and quirks. If you do, the user won't be able to find those important tidbits later without re-reading the entire section. In every "how-to" piece, focus is everything: give the procedural outline and just the procedural outline.

Include a goal-oriented "Tips & Techniques" section. I don't care what fruity name you give your product, there will be certain non-obvious tricks that make it more productive. Organize these by goals — e.g. Printing Fields From A Join, Timestamping A File, Converting File Formats. This section should be rife with cross-references and redundancy. Each goal's discussion should at least cross-reference related material that appears elsewhere, and include all the other "extraneous" information you were tempted to toss in as asides in the procedural section. Short, well-targeted examples belong here. Even if your product is "truly unique", the goals should be stated in terms of commonly recognized paradigms so that my experience with similar projects can speed my adaptation to your product.

Include a thorough technical specification. No, technical specifications don't help the beginner, but they are invaluable to an experienced user. Cross-reference the specs. Include hardware requirements, interface specifications, data structure templates, file specifications, and command-line syntax for subordinate modules (even for those modules that are normally invoked by some "integrated environment driver" — don't presume to know better than the programmer what he needs to know to get the job done).

Explain the design goals and philosophy. Virtually every product started in a specific environment with a specific, limited application in mind. Yes, marketing will want to promote the product as everything for everyone, but make room somewhere in the document for the truth. Sharing the design philosophy helps the programmer understand where the product fits and reduces the early frustration level. If I'm trying to use your tool in a development project, and I know the design goals that produced the tool, I stand a better chance of designing a project that can be built with the tool.

Invest in a superb index. So what if the answer to my question is in the manual. How many times can I afford to read a 900-page primer to find the two lines that are critical? The answer is a very small integer; I'm going to be calling customer support. Get your ego and marketing's time-table out of the way and hire a professional to prepare a SUPERB index. Every dollar spent on an index will be returned ten-fold in reduced customer support costs.

Explain the installation process for standard environments, and then explain what configuration options are available and how they interact. Give me this information even if you do bundle a whizbang installation utility. I've probably been at this long enough to have my own ideas about where to put my working files.

In short, keep your reader in mind. Design your documentation to meet the user's needs over his entire life as a user: a detailed step-by-step to orient the beginner; well-packaged goal-organized information to support the exploration and growth of the intermediate user; and comprehensive, frank, and well-indexed reference material for the experienced and technically advanced user.

I mean it.

Robert Ward
Editor/Publisher