The case of GNOME: improving community-generated online documentation

by Andy Oram

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.

Multiple approaches for multiple audiences

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

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.

Flexible approaches to conveying information

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.

Accommodate customization

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.

Make users into explorers

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.