Sep 6

Andy Oram

Andy Oram

Recent conversations about online documentation

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.

Motivation through a reputation system

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.

Streamlining contributions

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.

Who writes, and why?

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.

tags: open source  | comments: 6   | Sphere It

Previous  |  Next

0 TrackBacks

TrackBack URL for this entry:

Comments: 6

  Search-Engines Web [09.06.07 09:49 AM]

Whiles Motivation through a reputation system has merits, one flaw is that the 'ego-ism' involved.

Ideally, the INFORMATION should be the independent focus - not the person.

Eventually, could participants potentially be predisposed or biased in accessing the quality of information contributed by a high rep person - than if that same information was presented to them blindly. While there is a correlation of consistent quality - it is not without deviations.

One possibility would be to add unconscious behavior and social behavior into the assessments:
Examples would be frequency of revisitation, or bookmarking, or sharing, or emailing or backlinks.

Hopefully, by integrating various forms of evaluations - they can all neutralize many inherent flaws in one another.

  BlogOxide [09.06.07 06:58 PM]

Yes reputation system does work, but in many cases system abuse can be found. I really don't know the exact reason why people do so but some things I personally observed are lust of reputation (of course dishonesty) and ego. I, however, agree with the addition of assessment of social and unconscious behavior as presented by Search Engines Web.

  Nati Shalom [09.06.07 10:45 PM]

We moved to wiki based documentation based on Atlassian and that had worked very well for us. It helped us address our internal requirement for content management in a more collaborative fashion. In this way we could easily get more contributors to the content from our developers community. In addition to that we were able to provide means that enabled our users to navigate quickly through it and view in one page much more relevant information then they could previously done with the classic (book style) documentation.

You can see the
full story
on Attlasian web-site

Nati S.


  dave shields [09.07.07 11:01 AM]

There's an important kind of online documentation that I've been trying to produce lately -- detailed posts about a particular technical topic, with titles that have the form of a web search string, and now often see that someone has reached one of my posts by a web search. See for example, my
posts about Ubuntu.

Also of value are responses to online forums. I've starting building my own pile of Ubuntu beans, as described in and have become an active participant in the Ubuntu forums, and include links to my blog posts where appropriate. Indeed, most of the "referral" views of my blog these days come from people who have read one of my Ubuntu Forum entries and clicked on a link there.


  Andy Oram [09.07.07 11:32 AM]

I've been enjoying and learning from the responses to this
weblog--including the pointer to the proprietary Atlassian product,
which is quite relevant to the topic of the blog--all of which add up
to new "recent conversations" on top of the recent conversations that
sparked the blog.

Regarding egoism: when I started a survey about documentation, I
assumed selfish motivations would be important to contributors, and in
some ways they are, but a sense of community seems to be very powerful
as well--we don't have to worry about that sense being erased. The
interesting relationships between selfish and altruistic motivations
are laid out in my
article on the survey.
I think ego is also OK and that sites should offer ways to build

Because I envision people being rewarded for participating, combatting
fraud is important, but it probably requires intervention outside the
reputation system itself. The kinds of technical aids mentioned by a
respondent ("frequency of revisitation, or bookmarking, or sharing, or
emailing or backlinks") are good areas for exploration.

Regarding Dave Shields's post: it just so happens that I spend time on
an Ubuntu mailing list (although I haven't posted to it, I think), and
I included it in my
r\esearch on mailing lists.
The particular posting he points to, about the student traveling to
South America, actually elicited mostly pointers to topics that
required further research. This is useful but has to complement, not
substitute for, good documentation. There's a role for both volunteer
and paid tech support. I think there's also a role for both volunteer
and paid documentation.

  Dawn Foster [09.08.07 09:54 AM]


Reputation systems, like almost any online system, can be gamed. The key is to make the reputation system configurable to minimize the gaming behavior or make it transparent enough to be obvious when a user is gaming it. For example, you can configure the Jive reputation engine to give different numbers of points for correct or helpful answers to questions (based on what works best for your community). You can also view all of the responses for any user and judge the quality for yourself. In other words, a user may have a lot of points, but if other users see that they are getting the points without contributing in a meaningful way, they won't have much status in the community regardless of points attained.

Post A Comment:

 (please be patient, comments may take awhile to post)

Type the characters you see in the picture above.