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

Two words:

[Lazyhound]

Message boards.

Can't beat those for user-based support.

Re:Two words:

[Lazyhound]

Incidently, the irony of my post hit me about five seconds after I made it...

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

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

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.

inefficient?

[Tuxinatorium]

It's a lot harder to write documentation that somebody else wrote and didn't document than to write documentation on your own code. Why not have developers start writing some decent documentation for a change...

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.

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.

wiki used successfully on cocoon

[stinkyelf]

the wiki that cocoon uses works very well...

Not a good idea

[t_hunger]

I don't think the idea of community driven documentation is all that good. You wrote the program, you know how it works, so please document it! Users are great in pointing out areas you will need to improve, but they are not terrible good at writing the documentation in the first place: They don't know how your program works, so they have to guess (=> inaccurate documentation) or read and understand the code (=> usually start to develop themselves, forgetting about the documentation;-)

About a Wiki: Those tend to work rather well, contrary to what other people here claim. You need to monitor them regularly and frequently to catch all those changes by idiots that need to proof that a wiki is not secure (what a surprise! It's *editable webpages*, of course it is not!). That happens about once a month in our wiki or about 2000 times a day after being mentioned on slashdot (no, I won't give the URL here;-). Luckily most of those people are too stupid to da any real damage.

Anyway: I'd go for some annotation system like the one used by PHP and other projects where you have a fixed documantation text and users may add notes, ideas and questions to the static pages.

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.