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.

  • Tease the reader: If you don't have time to painstakingly describe a process from the user's point of view, just tell the readers what they can do and leave it up to them to figure out how. You could write an introduction like, "This utility lets you convert graphic files between different formats, embed one type of document within another, and change a number of characteristics such as resolution--try out various options to see what you can do." Such flippant advice works better with a graphical tool than a command-driven or programming-driven tool, but even in the latter cases, combined with a quick-ref, it can take self-starters surprisingly far.

    The idea of teasing the reader isn't an invention springing from my own desperation or sadism. It's an intriguing concept that goes back to the 1980s when a psychologist named John M. Carroll decided to try a radical break from heavy, desk-warping tomes that represented computer documentation at the time and to test a style of writing and training materials he called "Minimalist Documentation." His method stimulated users to try things out and build up their own mental models of how the software worked, rather than try to provide information and models verbally.

  • Accentuate differences: When writers handle the problem of limited time and writing resources in the most intuitively obvious way--describing the basic starting steps and the most common activities--they often leave out what's really interesting. The first 20 things you do with a spreadsheet or a scripting language are the same for all spreadsheets and scripting languages, and many users can move from one to another easily. It's the unique, advanced features that provide a competitive advantage for one system or another. Why not stress these advantages?

    The trick is to assume that your readers have had experience with the first 20 steps already, or that they can figure them out intuitively (see "Tease the reader" above) or can ask a more experienced colleague to show them what to do. Your goals are to explain the less obvious techniques, or, even more fundamentally, to let the reader know they exist. If each competing system documented its strengths well, users could evaluate them more easily and choose the one most appropriate to their tasks.

    As the documentation specialists can tell you, one of the persistent dilemmas in computer documentation is how to interest different audiences (for instance, both novices and experts). Your choice of the differences to accentuate depends on where your audience is coming from. For instance, few people coming from the Windows or Macintosh domains have experience with virtual screens or desktops (large spaces for holding windows, which the user views a bit at a time). But on Unix and Linux window managers, such virtual areas are commonplace. Whether you stress them depends on whether you expect your readers to have seen them before.

  • Celebrate diversity: Some users insist that every computer they use have the same software and that all files sent their way work with one set of familiar tools. But for those with eclectic tastes, you should help them move between your tool and the alternatives. If you've done research for the previous step ("Accentuate differences") you have at least a few examples of what other systems offer and how they differ from yours.

    One model for documentation I've always liked is the Free Software Foundation's manual for GNU make, which includes hints in several places about differences between GNU make and other versions in common use. In fact, it goes farther and tells readers used to features from other versions how to do some of the same things in GNU make.

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.