Linux Documentation – Needs and Priorities
By Andy Oram

For these reasons, newsgroups and mailing lists have emerged as critical infrastructure for the Linux community. (To some extent, that's true of other computer projects too.) And the incomplete state of Linux documentation affects both Linux adoption and the success of the people who adopt it.

In this article I'll detail some of Linux's documentation needs. Rest of the article is taken from a February 2004 presentation called Linux Documentation: What's There and What's Needed (http://www.oreillynet.com/pub/wlg/4357).

Three Audiences

The computer field has long divided documentation into three categories based on audience--end users, system administrators, and programmers-a division that applies well to Linux.

End Users

There are some good beginner's books for end users that succeed in the sense that they make Linux seem simple. If anything, I'm afraid they oversimplify. Sometimes things on Linux just don't work right, and readers are left stranded by step-by-step instructions that assume everything is in place for success. You need help to understand what is wrong when a configuration file has the wrong default setting, or you install a program and it fails to put a menu item on your start-up menu, or conversely, an item on your start-up menu fails because some file association is incorrect.

It's traditional to say that problems like these should be solved by making the software systems themselves more robust and by planning to make everything work together in advance. Just as when you buy a Macintosh, you should be able to install Linux and have everything just work. The end-user documentation should not have to deal with incongruities.

Certainly, standards for installing software and making programs interoperate correctly are valuable. But I fear the results of putting too many constraints on programs. Something of the openness of systems might be lost. In theory, one should be able to define standards that make all software work together robustly without excluding innovative developers. But in practice, developers on the fringe might lose out if Linux became like a Macintosh. So let's allow some flakiness around the edges and give end users documentation that help them deal with it--more on this later, under the section "Model-building documentation."

System Administrators

System administration documentation is the largest category in Linux, and a number of books address these areas well. It's gratifying to see so many books that provide background, take readers through complex processes step by step, and, most significantly, allow them to backtrack and trouble-shoot what they're doing.

Programmers

There is much less documentation for programmers on Linux, and the books that I do see on the shelves don't sell very well compared to the other kinds of Linux books.

One possible reason is that there just aren't many people writing programs for Linux, KDE, GNOME, etc. If that's true, it's a big problem that's going to bite Linux in the future.

It is more likely that the lack of interest in programming books is caused by the availability of other sources of information. If programmers can get what they need elsewhere, they won't buy many books.

And what do programmers always say is the best documentation? Source code! So that may ultimately be the explanation. When so many open source applications are out there for everyone to see--including the efforts of the best coders in the industry--programmers may be finding enough to get them going.

A Look at Documentation Trends

To pinpoint where Linux documentation is still weak, let's review a bit of the history of computer documentation.

Reference Manuals

The first computer documentation was an awful three-ring-binder reference listings filled with sentences such as, "The /x25 option invokes the X.25 protocol on the line." Nearly all documentation-- right from the beginnings of the computer industry until the 1980s-- was like this. But certainly, reference documentation is still important.

User-friendly Documentation

In the 1980s a revolt broke out among technical writers, who insisted on writing what they called user-friendly manuals. This led to sleek and glossy books with lots of little icons and tricks of layout (facilitated by the simultaneous rise of desktop publishing) and sentences such as "To print your document, pull down the File menu and choose Print." Actually, that sounds pretty much like the old X.25 example. Often, under the friendly exterior, the user-friendly documentation wasn't much better than the old stuff.

But this is being a bit unfair. The writers of user-friendly documentation tried to be task-oriented. When done properly, the documentation helped readers understand what their systems were capable of doing, and even sometimes helped them decide on their needs.

Model-building Documentation

During the craze to do user-friendly documentation with lines such as "To print your document, pull down the File menu and choose Print," few technical writers tried to think further or deeper about how to educate users. But another experiment was tried during the 1980s, a little-known movement called minimalist documentation.

The goal of minimalist documentation was not to convey facts--as was the goal of all computer documentation up to that time--but to help readers build the mental models that would help them solve, by themselves, problems they encountered. The movement was called "minimalist" because the documents were short and told the user as little as possible. Typically, they'd show some menu or dialog box and encourage the readers to play around with it themselves. The psychologists who invented this experimental documentation (I know of no commercial examples) deliberately wanted to set users free and force them to take responsibility for themselves.

Mental models help you figure out where to go to solve a problem. They help you guess that a certain setting must be missing from a certain file, or that a certain daemon is not running, or that the recipient of the data is not recognizing a certain data format.

It's very hard to form mental models. Readers certainly need background information, but simply having information thrown at them does not help. One must empower them to explore their systems. Metaphors and exercises are often critical. And that's where the Linux field, like many other areas of computing, can do better.

The Linux Documentation Project: An Important Case Study

Linux started to congeal and take off in 1992, and it was around the same time that the LDP appeared. The LDP is an impressive organization that has editors, guidelines for reviewers, procedures for updating documents, and translators. In short, it's an organization that has tried to reproduce everything about conventional publishers, but in an open and volunteer manner.

An all-volunteer organization experiences many stresses. For instance, having so many writers doing documents as short as three pages makes it hard to train the writers to do a good job. At all levels, people do a lot of unrecognized work, and the sensitive ones know how to hand over responsibilities gracefully before the burnout strikes.

The quality of its output, as one might expect, varies widely. At the high end, a few documents outrank the information in most conventional, published books. At the low end one finds mushy, vague descriptions of no interest to anybody, sometimes written by people for whom English is not only not a first language, but also not a language. Still, the LDP is a phenomenon we should all be following as a model for documentation in an open source community.

The LDP is a fine achievement, but it's fragile. One would be overly generous to say it runs on a shoestring budget. It basically has nothing but a Web site and a few tremendously dedicated and inspired volunteers who manage to keep the documentation flowing from multiple contributors.

They need an infrastructure, including the kinds of legal protections for which such open source projects as Apache, GNOME, and Eclipse set up foundations. People who care about documentation should talk to the companies pouring money into Linux and get them to set aside a little bit of those funds to put the LDP on firm ground.

STC India | Home | Contact Us

Copyright © 2003 India Chapter STC. All rights reserved.