informa
/
Commentary

Developers Suffer As Documentation Vanishes

Paltry documentation for developer tools greatly diminishes our ability to work well in subtle but important ways.

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 were 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.

Read the rest of this story on Dr. Dobb's.