Not so many years ago, products shipped as a combination of media and documentation. In the package itself, the manuals, printed on real paper, represented the true bulk and was often the first thing a new user would dig into. An inkling of how good the software would be was revealed by the quality and quantity of the documentation. A single, anemic-looking volume inspired no confidence and frequently set the experience of the software off on the wrong foot. A tool accompanied by multiple manuals, each carefully written and typeset, would receive a much more positive reaction. Vendors even competed on the basis of the docs they bundled. Microsoft and Borland were among the best on PC tools. At one point, Borland's Turbo C++ came with more than a dozen manuals, including volumes on the make utility, the bundled assembler, the libraries, and even one that was simply a tutorial on the C++ language. There was no doubt that if you wanted to become an expert in Turbo C++, you had everything you needed at your disposal.

Generating this kind of documentation was expensive, but viewed as an integral part of product delivery. This orientation began to change when the Internet, and specifically the Web, became widely used among developers. The number of manuals started to shrink. Materials that might be updated with information for new releases began residing only online as downloadable PDFs or Microsoft Help files. Eventually, all documentation and the software itself moved to downloadable formats. Vendors, when asked, pointed to the benefits of this: searchability, up-to-date information, lack of bulk, conservation of natural resources, and lower costs.

Then, as now, I found these reasons less than compelling. Searchability was rarely an issue. With a good index you could find what you needed without the now-familiar experience of clicking endlessly on search hits in a PDF document hoping one of them will take you where you want to go. Lack of bulk refers to the ability to carry the manuals with you. However, at the time, there were no tablets and few laptops, so sitting down to read a manual meant sitting at the console, rather than the previous ability to carry the manuals on a train or plane and thumb through them at leisure. And the cost savings, of course, were not passed on to customers.

If the decline of manuals had stopped there, I'd be happier than I am now. But in fact, the decline accelerated. Now, the information is available only on websites (the concept of purpose-written manuals essentially does not exist, save for a few exceptions). And even then, generally, the presentation is a reference volume. Look up a feature, function, or error message and you get a paragraph or two. But if you want to know how best to use a set of features and how they are expected to fit together, your prospects are very much hit and miss. Mostly miss.

For this, vendors provide forums of highly variable quality, while secretly hoping you'll go to other communities, such as StackOverflow, and bother your fellow users who will fill in the missing knowledge without tying up an employee.

Book publishers have been able to fill the gaps somewhat. O'Reilly tackled the issue head on by creating the "Missing Manual" series, which some vendors pointed users to with absolutely no sense of irony. However, those books were aimed at consumers. For developers, the gap has been filled at least insofar as open-source projects are concerned by two publishers in particular: Manning, with its "x In Action" series, and the Pragmatic Publishers. (One of their manuals is featured in this year's Jolt Awards.)

However, coverage of commercial tools by publishers is scant, with the notable exception of Microsoft Press, which covers Microsoft developer technologies in great detail, but at a hefty cost. (Going back to my earlier point, why do the versions of Visual Studio that cost thousands of dollars per seat not include the manual equivalents from Microsoft Press?)

The mindset that forgoes documentation or produces it with no particular attention to the developer's needs is so widespread that complaining about it puts one at risk of being viewed as a dinosaur pining for a lost past. But the cost is real. In conversations with developers, it's clear they do not know their tools nearly as deeply as they used to. The idea of discussing how one compiler manages the stack vs. another might seem a recondite point to many developers, but in fact, it can be crucial to choosing the right product and invaluable in low-level debugging. However, discussing implementation detail at that level requires serious communication and a commitment to good documentation from the vendors.

Lack of docs hurts the vendors, too, although in ways that can't be seen right away, so the costs are easy to overlook or discount. Developers who spend hours reading manuals to really understand how the tools and technologies work are loath to walk away from that investment. They become more attached to the tools because they know how to use them well. In addition to this loyalty, they have a much greater appreciation of new features in a release and can make convincing arguments to management for upgrading, because they understand in more than a superficial way the before and after feature scenarios and the benefits of the latter.

It's certainly possible that as we move in to a world of APIs, the appreciation of good documentation will return. If so, it won't be a moment too soon.

 Andrew Binstock

Editor in Chief

[email protected]

Twitter: platypusguy

Google+