Community-Driven Documentation for Free Software?

const_k asks: "I'm maintaining TightVNC, a popular free software project. As with many other free and open source projects, there is a problem with having comprehensive documentation. Currently, I'm thinking about launching a sort of community-driven documentation project, using Wiki as an engine that would help volunteer contributors to write and improve the documentation. I'd like to know, is it a good idea to use Wiki, and is it possible to achieve decent documentation quality this way? What software and technologies other free or open source software projects use, and what are the results, in terms of completeness and quality of the documentation? Any pointers and suggestions would be greatly appreciated."

Comments

Wiki's need ratings

[stefanlasiewski]

I'd like to know, is it a good idea to use Wiki, and is it possible to achieve decent documentation quality this way?

I prefer Wiki's over message boards because information in a Wiki usually has better organization (a good heirarchy) then in a Message Board, and it doesn't contain the level of kruft that you get in a BBS.

The thing I hate about Wiki's is that much of the information is of poor quality, questionable, or is way out of date. You often need a person to constantly go through the Wiki and fix info, remove old articles and goatcsx links, etc.

Some day, I dream of designing a Wiki that contains a rating system: Allow users to rate the info; and mark old info as "stale", which would hopefully encourage someone to update it.

Need a project outline

[Chacham]

Good documentation is written for good software. If the software is just thrown together, so will the documentation. Problem is, when documentation is thrown together, it is somewhat useless.

If the software has a clear outline, the documentation can have a clear outline. And so on. However, in many projects, there is no clear outline. Just a kernel, and where people want to take it. Thus, documentation ends up being limited to how to use this particular feature.

Take Linux for example. It is a bunch of tools thrown together. As such, each individual tool has its own manpage. Though, there is hardly a man page on the entire system. Linux tools are written on a "gee, I need this" basis, and so, without a clear outline, there is no decent overall documentation.

With software in the open source world being written on an "I need this" basis, and then these people donate their time and energy, and outline may very well only hinder the process. But the documnetation aspect will suffer therefore.

Re:Need a project outline

[Rick the Red]

Try coding the software after writing the documentation. Writing the documentation first, describing what the software does and how to use it, can uncover many problems/opportunities just as easilly as writing code does. For example, thinking of better ways to organize the user interface; or realizing that if we're asking them for X, Y, and Z then if we also ask them for W (instead of hard-coding W) the code will solve a larger class of problems.

First get the documentation to the point where you (or the friends you get to proofread it) think, "Wow, this software's really cool, I can't wait to try it," then start coding.

As your own customer, you're in a unique position to do this. In the "real world" we usually have trouble getting a Requirements Document out of the customer; I'd love a project where the customer said, "This is the user's manual for the software we want." Given a good user's manual the code would practically write itself. (bonus: then they couldn't complain about the user interface :-)

I think Wiki would be terrible for documentation

[Tim_F]

First of all, it would prone to heavy abuse. Having a documentation system world editable will lead to the possibility of countless exploits. However, setting up a cvs server where contributors could send documentation, knowing that what they write would be edited may be a better approach. It would work just like OS software projects. One person would be the doc maintainer/editor.

Re:inefficient?

[AlecC]

What you say is true for maintainance documentation, but not for user documentation. One of the troubles with a lot of Linux projects is the lack of user documentation - until the project gets big enough to get the O'Reilly (or similar) book. There is a gap between the small project, supported by a maillist with the developers still on it, and the giant project which can support a proper book (and pay someone to write it).

A wiki would sound good to me. Thinking about the above poragraph, you need to think about if tghe time comes when a publisher offers to publish thw Wiki as a book - if someone will clean it up. On the one hand, that poewrson will want to be paid/get royalties to do it. On the other, they will be using other people's copyleft words, not as is the case for other books, writing about other people's copyleft code.

PHP docs are a great example.

[cornice]

My favorite docs are at the PHP Site. What I like is that they are first and foremost very complete and well organized but what I also have grown to really appreciate is the notes that are made within each section. It's very easy to document bugs or unexpected bahavior in that system. That said, I suspect that a lot of time and effort went into the PHP documentation. I would bet that a wiki system would work as long as a developer starts with a comprehensive outline and a developer or trusted individual combs the docs regularly to correct poor and inacurate information and to consolidte ideas. Actually what I think would be the ultimate system would be a Wiki with restricted access along with an unrestricted attached message board (like php.net). This would allow the people who really want to get involved to have access to the the entire system and allow casual users to contribute and discuss issues without breaking the core.