The Death of Documentation
I have a song stuck in my head, only the words are slightly twisted. I keep hearing Pete Seeger singing, "Where have all the manuals gone, long time passing?" I’m worried that it will be a while before I stop mentally humming along.
Aside from this week, when I pleasantly surprised by the excellent WebSTAR 3.0 manual written by Avi Rappoport, I can’t remember the last time a product’s documentation really impressed me. Heck, many products these days don’t even come with printed manuals. What has happened to the fabulous manuals of yesteryear, the books that taught something that wasn’t obvious from the interface? I admit that well-done manuals have always been the exception rather than the rule, but I remember a few that stood out. The first Suitcase manual had an excellent discussion of how fonts worked on the Mac. And early versions of the Norton Utilities manual provided detailed information on Macintosh disk structures.
Today’s manuals, when they exist on paper at all, more closely resemble booklets than books. Size alone is of course not an indication of quality, but no one is more capable of producing accurate and comprehensive reference information than the company that creates a program. Independent books can be better written and organized, and more honest about a program’s shortcomings, but most authors can’t obtain the access to developers and testers that in-house writers enjoy.
Look at the just-released Microsoft Office 98. It’s composed of three complex, powerful programs in Word, Excel, and PowerPoint, and yet the only printed documentation is a trio of slim (248 pages for Word, 244 pages for Excel, and 160 pages for PowerPoint) "Getting Results" manuals that provide task-based help to experienced users. The introduction to the Word manual even says, "The people who will find this book most useful are those who have been using Word for a while and who can usually do what they want to do with the application." Novice users are pointed at the 50-page Getting Started chapter, which covers only the absolute basics, whereas advanced users and system administrators are sent to the Web-based Microsoft Office Resource Kit (also available as a $60 book from Microsoft Press).
<http://www.microsoft.com/office/ork/>
<http://mspress.microsoft.com/prod/books/ 1329.htm>
Short of one truly confusing stylistic issue (on the Mac, you don’t click menus, you choose items from them), Office’s documentation isn’t even bad – task-based help is extremely valuable. It’s just incomplete, since it lacks the serious reference information that Microsoft used to provide and that a number of TidBITS readers have already missed. The Microsoft Office documentation is only one of many examples of skimpy documentation I’ve seen of late, such as Qualcomm’s Eudora Pro 4.0 manual
Manual Migration — So where have these manuals gone, and why have they left us? The primary reason is cost. It takes money to hire talented technical writers to produce a useful manual, not to mention printing costs. Large manuals also increase the weight of the packaging, resulting in increased shipping charges. As a case in point, Casady & Greene’s recently released $80 Grammarian comes with an electronic manual; the printed manual costs an additional $15.
<http://www.casadyg.com/products/grammarian/>
But if these restrictions of the physical world were the only limits on shipping excellent manuals, we’d see well-done electronic documentation, and for the most part, electronic documentation is as bad as – or worse than – what makes it to paper these days. I think the reasons for lousy documentation run deeper.
Apple deserves a small portion of blame for this trend toward poor documentation because by forcing Macintosh programs to look and work much the same for basic tasks, Apple has made programs easier to use. Systems that lack conventions, especially if they also lack graphical discoverability (think of the DOS or Unix command line) are more likely to require documentation – how else would anyone figure them out?
We users must also shoulder some blame. After all, the mantra of the Macintosh user has always been, "I never read manuals." For the most part, we don’t. Users expect software to be so easy to use that the manual is merely a superfluous appendage. Some products are that simple, but many aren’t; too bad it’s cheaper to ship a pamphlet that makes a product look simple, even when it’s a complex, powerful program.
I’ve seen the same trend in computer books. As the author of a bona-fide tome – Internet Starter Kit for Macintosh – I was astonished at how many people wanted less information. They weren’t offended at the cost; they just didn’t want to read the entire book and didn’t like the idea of skipping clearly labeled sections that didn’t apply to them. "Fascinating," I thought. "If I took this to the logical extreme, people would pay $30 for no information at all!"
I’d also like to pin the tail of blame on the Internet. As much as I believe in the leveling force of the Internet as a democratic publishing medium, much of what I see online lacks the polish of professionally written, organized, and edited text. Lack of polish is acceptable if the quality of the information remains high, but much of what’s on the Internet is of such poor quality that it lowers the bar for what’s expected, especially for electronic documentation.
Finally, the people who write manuals generally have their facts correct and are usually competent, if not inspired writers. But they’re not teachers, people who make their living working on the best ways explain complex topics to a wide range of audiences. It’s not easy to figure out the best way to phrase and organize information, and the needs of the reader must always remain in mind. Those who lose sight of helping the reader learn inevitably turn out a mediocre manual.
Switch to Automatic — Far be it for me to moan about the state of documentation without offering suggestions for ameliorating the situation.
First, based on comments I’ve received about my books, I believe all writing should have a voice. Show some attitude and let a personality come through in documentation. One fascinating example of this problem is Microsoft Office 98’s documentation. The printed manuals and the online help are pretty dry, but one of the program’s major features is the addition of Max, the personable Mac-like Office Assistant. Although Max’s antics can annoy at times, those who like him do so because he’s fun. The manuals and online help would benefit from a touch of that personality.
Second, online documentation requires consideration and care to do well. The first decision involves the electronic format, and you should think about that before starting the documentation process. For instance, many companies just print their manuals to a PDF document and ship Acrobat Reader along with the software. That’s a cop out and in most cases results in almost unusable documentation.
If you use PDF, create a design that can be read onscreen as well as a design that can be printed. The onscreen version should use common screen fonts and utilize PDF features like navigation bookmarks and links. PDF files should also mention Acrobat’s searching capabilities – you can’t assume people are expert Acrobat users. Searching is important – if you use some other electronic format, make sure it’s searchable! An example of good PDF-based electronic documentation is the manual for Dantz Development’s new Retrospect Express. Although it’s a little disappointing that the program comes with only 12 pages of printed documentation (for each of English, French, and German), the online manual is complete, well-written, and designed for the screen (though it includes printing tips too). It also provides navigation bookmarks and even has a "hot" table of contents and index in which you can click headings to jump directly to the associated page.
<http://www.dantz.com/sp/808.html>
Although PDF is relatively easy to create, especially for an electronic version of a paper manual, HTML may be more common these days. However, an HTML version of a manual isn’t necessarily ideal either. Web browsers can search only in a single page, not through a set of Web pages (though you could link to an online search engine on your Web site). Also, provide plenty of navigational controls, since otherwise moving around within the manual will prove frustrating.
With an Open Checkbook — Large companies have the least excuse for shipping substandard manuals, especially with their flagship products, which often retail for hundreds of dollars. Good documentation may increase development costs, but these companies already spend vast sums of money on documentation.
For large companies, I think the solution is simple. Bring in a professional author to write the manual. Just look at all the independent books out there on any given program. Many of those books will sell no more than 10,000 or 15,000 copies, making the author between $10,000 and $20,000, before taxes. A large, successful company could easily spend $40,000 or $50,000 to hire someone (or even a group) to produce a top-quality manual. Sure, the author won’t have a chance at royalties from a best-seller, but many publishing companies are currently pushing authors to write books as "work for hire," where royalties never enter the picture anyway.
The argument that there’s more than just writing involved in creating a manual doesn’t fly either. Experienced authors often do much more relating to book production than just writing. Some publishers make authors responsible for the index (professional indexers are always better than amateurs – see David Holzgang’s article "The All-Important Index" in TidBITS-333) and require authors to submit PostScript files. For instance, for my Eudora Visual QuickStart Guide, I did the writing to Peachpit’s style, laid the book out in a QuarkXPress template file, convinced Tonya to do the copy editing, and paid an indexer to compile the index.
<https://tidbits.com/getbits.acgi?tbart=00963>
If a large company isn’t interested in finding an individual author, why not contract with a publishing house for the same services? Adding a publisher would increase the cost, but might result in an even higher quality manual, since publishers have professional editors and production departments. At the very least, publishers are already publishing these books. I’d happily replace most manuals I’ve seen of late with Peachpit’s Visual QuickStart Guides, although they’re task-oriented and don’t include detailed reference information.
Producing a good manual can decrease technical support costs, but many large companies now charge for support, so reducing the need for support may not be an advantage. In fact, conspiracy theorists might posit that shipping a lousy manual will increase support’s bottom line.
Documentation on a Shoestring — What about small companies? Although the possibilities might seem grim, small companies don’t face the same concerns because they’re likely to produce less complex products. This isn’t to say that small products can get away without documentation. A good ReadMe file is essential, particularly for software distributed solely via the Internet. Tonya has written several articles on this topic over the last few years, mostly in response to being irritated by lousy ReadMe files.
<https://tidbits.com/getbits.acgi?tbser=1039>
Essential though a ReadMe may be, most programs also require manuals. Although small companies probably can’t afford a professional writer, allow me to suggest this simplistic template for a manual. Don’t feel bound by it, but if you can fill in these sections, you should end up with something acceptable.
Table of Contents: They’re short and easy, and always worth doing. If a table of contents seems too short or the chapter titles aren’t sufficiently descriptive, add a sentence or two of explanation beneath each title.
Introduction: Explain what your program does and why someone would want to use it. Don’t assume that people know this information already. Providing usage examples may help users get started.
Requirements & Installation: Always list the system requirements for your program so users don’t install before realizing their Mac can’t run your software. After that, turn to installation, making sure to address previous users if it’s an upgrade. Always provide a list of exactly what’s installed where, especially for items in the System Folder.
Getting Started: In this section, provide step-by-step instructions for performing basic tasks in your program. Don’t explain everything; instead provide a tutorial that helps users gain a feel for how the program works and what they can use it for. Sophisticated users will skip the tutorial, but given that the Step-by-Step chapter in Internet Starter Kit for Macintosh was always extremely popular with novices, I’m convinced of the utility of this section.
Reference: This is the trickiest section. You don’t want to document obvious stuff that exists in all Mac programs (like how to quit); instead look to explain capabilities unique to your software. You can organize the reference section so it documents menu commands and dialog boxes; however, it also pays to organize documentation around what people can do with the software, and then tell them how to do it, regardless of what commands must be employed. In particular, cover features that are somewhat hidden.
Troubleshooting: Even if your software is perfect, it’s running in an imperfect world. Always discuss what might go wrong and how to troubleshoot problems.
FAQ: Although a Frequently Asked Questions list may seem strained in the first version of a product (make up the questions and answers), keep track of questions for future versions. Even if you decide not to put your entire manual online, put the FAQ on the Web – FAQs are tremendously helpful to existing and potential users.
Index: I know I said you should hire a professional indexer if possible, but if you don’t have the budget for it, try to do an index on your own anyway. Beware of automated index generation tools in word processors and desktop publishing programs, since a good index doesn’t include each instance of a given word; instead, it indexes appropriate instances of important words and concepts.
I won’t pretend that creating useful documentation is easy, but I think it’s a worthwhile effort, especially for increasing customer satisfaction and reducing technical support costs, which can be significant especially for smaller companies and individual developers.