Published on O'Reilly (http://oreilly.com/)
 See this if you're having trouble printing code examples

Finding Resources for the Documentation of Competing Alternatives

by Andy Oram

Everybody acknowledges the value of competition in technology, but powerful forces clearly pull the computer field toward monopolies--and not just at high levels among conniving corporations. How many users have complained about a mail problem, or something equally mundane, to their system administrators and been told, "Just switch to Microsoft Office; I know it better, and that's what everybody else is using anyway."

Now I have a confession to make. Writers and publishers like monopolies too. Oh sure, it's exciting to jump on a little-known topic and be the first out in the market with a book, but those books usually generate more good will than revenue. Even though writing about Microsoft Office or Visual Studio plops us into the same tub as many other writers and publishers, it's a big enough tub to be worth fighting over from a financial point of view.

The corollary is that a lot of technologies are left orphaned when it comes to documentation. For instance, seeing the small market for BSD (in fact, a plethora of BSDs), most writers just ignore it and cover Linux. One can see the same trend for database products, networking tools, and other technologies. Where two competing packages (or alternative packages, as free software developers might prefer to say) have installed bases of comparable sizes--like KDE and GNOME--I believe that they both suffer. Combining alternatives in a single book is difficult to carry off and dissipates one's efforts to interest readers. In a field marked by multiple alternatives, each team has to strive for efficiency in making the most of the writing talent they attract.

Why it takes time and talent to produce good documentation

Most programmers realize pretty quickly--with the first email or phone call from a user--that they need better documentation than a quickly whipped-up man page, or even the user manual they honestly strove to write. Many learned observers have discussed why it's so hard to write good documentation for computer software, even by people who know it through and through, but I believe the problem ultimately boils down to structure. Teams think in terms of the structure of a program, but end-users approach it from a structure involving common tasks and the environment.

For instance, to develop a "Save File" dialog, you might write a function that streams a buffer to the filesystem, a function that checks permissions, a function that organizes files by suffix and directory, and a function that expands wildcards. All those activities may be worth explaining to the user, but only if they're presented in the integrated way the user encounters them in the dialog. The difference between the program structure and the user view explains why literate programming technologies like Donald Knuth's WEB never took off. (Knuth seems to have conceived of WEB as a tool for teaching people how to program, and it can be useful in that narrow context--but not as end-user documentation.)

When you take the problem to higher levels and realize that each user task combines many interactions with your software, many pieces of software from different sources, and many pieces of the user's environment, you start to wonder whether any documentation can ever be adequate. I've explored possible solutions in earlier articles (for instance, Methods and Mechanics of Creating Reliable User Documentation), but the bottom line is that you've got to find someone with a special knack to do the job, and give him or her both time and training.

When both time and training are limited, I'd like to suggest some shortcuts that software teams can use to document their software while taking into account that there are alternative, competing packages.

The goal: promoting alternatives

I believe in the benefits of alternatives. For example, the co-existence of KDE and GNOME allows their teams to experiment with a number of philosophical choices carrying valuable implications. Is it better to code in C++ because it provides high-level shortcuts, or in C to make integration with other languages easier? Is the flexibility of CORBA worth the hassle of learning its conventions? We may have more evidence with which to determine answers, thanks to the test-tube environment provided by the two teams.

BSD and Linux have also been good for each other. From the BSD project, Linux has taken not only massive amounts of working code but the attitude that it is destined for greater things than a hacker's desktop. In turn, Linux has shaken the various BSD teams out of the blues that hit them in the early 1990s and led them to say, "If Linux can get that far, so can we." For lots of reasons I like to see alternatives flourish in the world of computing, and good documentation is one important way to bring them into greater circulation.

Copyright © 2009 O'Reilly Media, Inc.