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.

IoT
IoT
Software // Enterprise Applications
Commentary
9/25/2014
11:10 AM
Andrew Binstock
Andrew Binstock
Commentary
50%
50%

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
Comments
Newest First  |  Oldest First  |  Threaded View
zaious
50%
50%
zaious,
User Rank: Ninja
9/29/2014 | 12:10:05 AM
Re: You're not a dinosaur if you like documentation
Documentation is important, period. I agree that, finding solutions online is a blessing, but a well written document can save time and labor ( doucment may come in a soft copy -I do not mind as long as it is well prepared). 

I feel blessed by another addition "Online Forums". They are filled with helpful people and mot of them can answer because they know a lot by doing and reading the documentation. 
Charlie Babcock
100%
0%
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.
News
The State of Chatbots: Pandemic Edition
Jessica Davis, Senior Editor, Enterprise Apps,  9/10/2020
Commentary
Deloitte on Cloud, the Edge, and Enterprise Expectations
Joao-Pierre S. Ruth, Senior Writer,  9/14/2020
Slideshows
Data Science: How the Pandemic Has Affected 10 Popular Jobs
Cynthia Harvey, Freelance Journalist, InformationWeek,  9/9/2020
White Papers
Register for InformationWeek Newsletters
Video
Current Issue
IT Automation Transforms Network Management
In this special report we will examine the layers of automation and orchestration in IT operations, and how they can provide high availability and greater scale for modern applications and business demands.
Slideshows
Flash Poll