Developers Suffer As Documentation Vanishes - InformationWeek

InformationWeek is part of the Informa Tech Division of Informa PLC

This site is operated by a business or businesses owned by Informa PLC and all copyright resides with them.Informa PLC's registered office is 5 Howick Place, London SW1P 1WG. Registered in England and Wales. Number 8860726.

Software // Enterprise Applications
11:10 AM
Andrew Binstock
Andrew Binstock

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.

Prior to joining Dr. Dobb's Journal, Andrew Binstock worked as a technology analyst, as well as a columnist for SD Times, a reviewer for InfoWorld, and the editor of UNIX Review. Before that, he was a senior manager at Price Waterhouse. He began his career in software ... View Full Bio
We welcome your comments on this topic on our social media channels, or [contact us directly] with questions about the site.
Comment  | 
Print  | 
More Insights
Newest First  |  Oldest First  |  Threaded View
Charlie Babcock
Charlie Babcock,
User Rank: Author
9/25/2014 | 6:31:01 PM
You're not a dinosaur if you like documentation
Andrew is right, there's been a penalty to doing away with physical documentation. The electronic replacement is not its equal or the equivalent of the same investment. This is not simply a retro attitude. Abandoning the printed materials allows a less-invested effort to come in as the replacement, and those who notice are subject to dodgey, old foggie branding.
InformationWeek Is Getting an Upgrade!

Find out more about our plans to improve the look, functionality, and performance of the InformationWeek site in the coming months.

How CIO Roles Will Change: The Future of Work
Jessica Davis, Senior Editor, Enterprise Apps,  7/1/2021
A Strategy to Aid Underserved Communities and Fill Tech Jobs
Joao-Pierre S. Ruth, Senior Writer,  7/9/2021
10 Ways AI and ML Are Evolving
Lisa Morgan, Freelance Writer,  6/28/2021
White Papers
Register for InformationWeek Newsletters
Current Issue
Flash Poll