This work is licensed under a Creative Commons Attribution 4.0 International License.
By Andy Oram
This article was originally published on the O’Reilly Radar site on September 6, 2007.
Computer documentation has long been like government funding: nobody wants to contribute to it, but everybody wants it to be there when they need it. In considering the free, online documentation produced by amateurs for open source projects, there are other somewhat whimsical ways it can be compared to government funding:
It’s allocated haphazardly, reflecting the interests of “whoever shows up at the table.” (In documentation, each volunteer writes about what he or she finds interesting.)
The prerequisites needed to make it effective are sometimes missing. (Advanced topics and fussy details may get into the documentation without background material.)
Efforts are not sufficiently coordinated to achieve the results they merit. (Authors don’t check for overlaps, gaps, and consistency.)
Enough strained metaphors—I am now happy to say that attitudes seem to be shifting in online documentation. Major projects are hiring authors or coordinators for amateur contributions. They’re undertaking large tutorial works and trying to organize the documentation along more rational lines, usually through wikis or content management systems.
My own goals are to find technologies and practices that promote user-contributed documentation, and to find a role in this space for my work as editor and O’Reilly’s work as a publisher and information disseminator. Recently I’ve discussed the topic and the results of my research at a number of conferences and other public events, and had a chance a chance to exchange email with a number of interesting people working in the area.
A survey answered by 350 contributors to online documentation showed that building reputation could be a useful motivation for getting people to contribute, although reputation interests them less than community-building. As I point out in the article, enhancing chances for building reputation may help to attract the people who tend to provide high-quality documentation: trainers, consultants, and others trying to fashion a career around a technology.
I was thus happy to be introduced by open source activist William Hurley to a simple, flexible reputation system for a mailing list or forum. His company, BMC Software, has implemented this reputation system, which is a part of the Jive Forums product, on their developer network. As described, the system lets participants label their postings as “questions,” and then rate each answer as “helpful” and “correct.” The people who earn the most points through helpful and correct answers are posted on the site, thus furnishing them with a reputation on which they can build a business, while helping new members of the forums learn whose postings are particularly worth reading.
I had several discussions with Adam Hyde of FLOSS Manuals, which provides tools to facilitate the creation of documentation for free software. Hyde has built a formatting layer on top of the popular TWiki software so that documents can be presented as more attractive web pages.
FLOSS Manuals has also recently started printing and selling books; the first one (on the audio editing utility Audacity) is available at their own site or Lulu. Whereas most publishers (including O’Reilly) struggle to automate the conversion of documents between online and print formats—a process that never goes smoothly except for very simply laid-out documents—Adam just bytes the bullet and pays someone to manually put the text into InDesign. The process takes a couple days per book. They’re moving to Scribus for print-ready layout, and plan to develop plug-ins that make conversion from wiki format to Scribus format more automatic.
The provision of different formats for the same documents leads to a two-stage system. FLOSS manuals have a development version that can be viewed in the standard TWiki format, and a stable version that gets put up in the attractive format and printed.
FLOSS Manuals also offers a facility for mixing sections from different documents. Their “live manual” function lets people serve a remixed manual on a new website by just pasting in five lines of HTML.
I exchanged some very interesting mail with Lance Smith, who believes that people who write documentation have an artistic bent and are chronically unsatisfied with the sloppiness that accompanies most of the work they see around them. The urge to intervene and tell people how to use their computers is aesthetic. The kind of person who contributes to mailing lists and web pages just finds it demoralizing to see bad practices carried on by generation after generation of new learners.
While this is a hard hypothesis to test, it fits nicely with the skills I see as necessary for writing good documentation: a sense of when a passage looks and sounds right, combined with the determination to revise and rework the passage until it reaches the quality that the author can live with.
This work is licensed under a Creative Commons Attribution 4.0 International License.