Based on my experience as a tech writer and a few books I’ve written since then, someone recently asked me for advice on documenting a complex software product, and I thought I’d share my advice here. After writing it I remembered that two years ago I submitted a proposal to O’Reilly for a book on writing about software. After kicking the idea around with Simon St. Laurent a bit, I decided not to go through with it. One thing that put me off was his warning that a place like O’Reilly was obviously full of people with very specific opinions on the subject, so a settled outline alone was starting to sound like too much work. Since I had gathered some potentially useful material, and this is a weblog where I can put my opinions and leave others’ opinions to their own weblogs, I’m going to make this a series. If you’re at a small software company, or thinking of launching a product, or just interested in augmenting your coding skills with some complementary prose writing skills, it may be useful. Big software companies already know all this (in fact, we’ll see that they provide some very handy resources), and everyone else won’t really care. This first installment addresses the question that I was recently asked: what documentation does a software product need?

The most popular approach since the beginning of the PC era is to think in terms of three volumes, or, if you’re not creating bound, hardcopy books, three sets of information that should be easily available to the user. To let my tech writer roots show, I’ll put them in a bulleted list:

• Getting Started: (a.k.a. Tutorial) Assuming that the product in question lets the user create software widgets, this leads a user with only a vague idea of the product’s use through the minimal amount that he or she needs to know to get some work done. It may start by walking you through the loading of a widget into the product and demonstrating basic tasks that you can do with a loaded one. Then, it leads you through the creation and use of a new, much simpler widget. Finally, it describes the other things that you can do and describes where to find out more about these tasks in the other two volumes. The combination of this Getting Started guide and a free version of the product make an excellent marketing tool.

  When putting something like this online with no hardcopy version available, remember: the classic advantages of hypertext fall short here, because after a given section, users don’t want a choice of where to go next; they won’t know where to go. They want to be shown. That’s why they’re reading the “Getting Started” manual.

• User Guide: (a.k.a. User/Users Manual) a task-oriented approach to using the product. For each “how do I do X?” that may come up in the user’s mind, there should be a corresponding entry in the User Guide table of contents.

• Reference Guide: (a.k.a. Reference Manual) everything the user might want to know, organized more like the product itself. For example, every menu entry and dialog box should have an index entry. This volume should answer every “What’s that for?” question a user might have while using the product. It should also make it clear how to get to those dialog boxes and menu choices—I’ve seen too much documentation that tells me to set something by filling out a particular field on some dialog box without giving me a clue as to where to find that dialog box.

The User Guide is the most work here, because the Getting Started manual can be written in a weekend and the organization and content coverage of the Reference Manual will be self-evident from a detailed review of the product. The User Guide must solve the users’ problems, and assembling a reasonably complete list of potential problems is much more difficult than listing all the menu choices and dialog boxes.

When I first decided to write XSLT Quickly, which took a user guide approach to the language after the tutorial in the first twenty pages, I deliberately drafted a table of contents before I had learned much of XSLT. From years of writing Omnimark programs to process SGML, I knew the important tasks faced by someone developing markup conversion programs. I knew that a section title like “Getting the most out of xsl:output” would be useless to someone learning XSLT, so I had titles like “Non-XML Output” and “Whitespace: preserving and controlling.” (Lord knows the latter is a common problem with XML processing.)

Should you deliver documentation as printed, bound books? As online help included with the product? As HTML files on your company’s website? Be prepared to deliver all of them, as well as formats that haven’t been invented yet. This is why people store such documentation in DocBook XML and, increasingly, DITA; it’s also why so many first-generation XML geeks started off as SGML geeks employed as tech writers at software companies: they had to create content that could be mixed and matched and published in multiple media. At Information Builders, I developed scripts to convert documentation into online help for mainframes, OS/2, Unix flavors, and Windows winhelp—remember hlp files? The main target for IBI at the time, though, was always printed bound books. If you’re planning to develop these three volumes and online help, the Reference Guide will provide the bulk of the on-line help material. Clicking the Help button on the Foobar dialog box should lead to the same information that the “Foobar dialog box” index entry points to in the printed Reference Guide.

Once, when I complained about the difficulty of using a product’s documentation, a saleswoman from the product’s vendor kept saying “but it’s all online!” as if that alone made it wonderful. I replied “Yes, but the online documentation is badly organized, and I can never find the answers I need.” (Have you noticed lately how a Google search on the use of a particular Microsoft Word feature retrieves a good answer faster than Word’s built-in online help does?) A lack of paper documentation does not absolve the designer of a product costing hundreds of dollars from an obligation to help users quickly find answers to questions that fall into three categories: How do I get up and running with this product? How do I make the product do this particular task? What will that aspect of the product do for me? These answers may or may not be grouped under the headers “Getting Started,” “User Guide,” and “Reference Guide,” but a clear representation of these three concepts will help users get more efficient work done with the software product, turning them into happier customers.