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.

LFS

[GreyWolf3000]

The Linux From Scratch book has a cvs system in place, and automatically converts to html, xml, txt, ext from the sources (which are TeX now iirc).

But Seriously

[McCarrum]

I've found running TikiWiki to be fantastic. Running under the usual LAMP system, it does much more than the atypical wiki; forums, trackers, faq's, dynamic content, image and file galleries, etc etc etc.

I've been using it for building a knowledge base, and all the extras have just been the icing on the cake. Two thumbs up.

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.

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 :-)