Andy Oram
December 6, 2004
Pushing forward GNOME documentation and other community efforts: multiple approaches for multiple audiences, flexible approaches to conveying information, accommodate customization, and make users into explorers.
For a couple of years I've been researching community computer documentation--the kinds of volunteer efforts produced by the Linux Documentation Project, the GNOME Foundation, and others--with the aim of finding ways that it can be improved by volunteers and project leaders. It's natural that I should be interested in a source of information that most computer book publishers identify as their key competition. More fundamentally, I can tell that people look to their fellow computer users for information, and that these peers have lots to offer. I hope that, by helping the community documentation movement to mature, I can persuade them they also need the help of professionals like me and the other folks at O'Reilly.
I had a discussion last Friday with Tim Ney, executive director of the GNOME Foundation. We came up with several interesting points that we thought would interest others who care about computer documentation.
One nice thing about online documentation is that a site can provide an unlimited number of documents for different users at different stages of development or different entry points. The GNOME site, for instance, could have a document for Windows users migrating over to GNOME, a document for Mac users migrating over to GNOME, and so forth. I say more about this (and other topics in this blog) in my article on community documentation:
Splitting Books Open: Trends in Traditional and Online Technical Documentation.
And the nice thing about community-generated online documentation--as a special case of online documentation--is that your own users can contribute such documents as the urge comes to them. You don't have to set up a committee or manager to choose what's written and allocate resources.
That freedom comes with disadvantages, too, of course, as my article explains. A project can end up with five overlapping documents written for the same audience, and be deprived of documents that serve other equally needy audiences. One way project leaders can encourage volunteers to contribute the necessary documents is to develop a high-level table of contents and invite readers to fill it in.
For most computer users, it would be a waste to write a totally introductory document about GNOME--one that tells them, for instance, that defines what an "icon" is and tells them they can start programs by clicking on icons.
But maybe it wouldn't be a waste after all. GNOME is gaining traction in many parts of the world where you can't take it for granted that users have used computers before. They need help understanding what an icon is. But do they need a manual? That leads to my next point.
Not every training situation deserves a manual, or should be solved through one. Perhaps what new users need is a laminated sheet with a few simple instructions to get them started. It could point them to a tutorial online. (Tim and I agreed that we had both tried Emacs's help-with-tutorial function early in our relation with that editor, and that it was quite useful.)
Some people need Hands-on or platform training. The GNOME Foundation does that for developers now, sending developers long distances to provide it. They could film the trainers and try to figure out what works. Perhaps the approach used for training could be frozen in text somehow and turned into a manual.
(It's worth noting that one of the most ground-breaking approached to computer documentation, the O'Reilly Heads First series, was developed by two trainers.)
And what does that nascent new user need? Is it the same at every site? Not at all, as we'll see next.
GNOME documentation has to deal with an incredible diversity of implementations. Few users get the desktop layout--menus, icons, and panels--the way the GNOME Foundation released it. Every provider customizes it extensively. And not just commercial providers. Tim pointed out that when GNOME is installed in the Spanish region of Extremadura, the icon for the chosen word processor is a picture of the head of Cervantes--an image that apparently resonates for even a moderately educated Extremaduran.
The customization continues as different administrators install the software at their sites. So that laminated sheet I mentioned earlier should probably be written by the administrator.
For reasons just explained, experienced desktop users have found that they shouldn't expect their favorite tools to be in the same place on different systems. (This is true even when moving from one Windows XP system to another.) Experienced users expect that the tool they need is somewhere, so long as its moderately popular. They go looking for it. For instance, when I boot a GNU/Linux system I don't know which IRC program was installed, but I expect there's one somewhere and I navigate the menus till I find it.
Thus, what desktop documenters have to do is explain all the wonderful things that systems can do and make users want to do those things. The range of computer tools for all types of activities--media, communications, and even system administration--is so great that nearly any computer user can become more empowered and productive if they try new ones out. Once they have an idea what they want to do, they can find the tools on most GNOME systems regardless of where the vendor or administrator has placed them.
This goal--the inquisitive user--is the thrust of the most interesting experiment in computer documentation I've found, minimalist documentation. The approach of minimalist documentation is pretty much to say, "Try out this thing and see what happens."
So the search for effective community documentation continues. I'll keep you informed as I learn more.