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

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.

Re:Wiki's need ratings

[Karora]

You mean like Everything 2 [everything2.com]?

LFS

[GreyWolf3000]

The Linux From Scratch [linuxfromscratch.org] 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 :-)

Re:Need a project outline

[Chacham]

Hmm.. Not a bad idea. Not bad at all.

I will say that this is the UI specification, but documentation would be good at it too.

But Seriously

[McCarrum]

I've found running TikiWiki [sf.net] 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.

Documentation features

[DamienMcKenna]

Tiki 1.5 added some (hidden) features that would help with documentation, notably a system for structuring Wiki pages into a book-like structure. You'll need to search the dev list archives for information on how to use it though, it won't be making its official presence felt until v1.6 is released but it is there and does apparently work well with 1.5 anyway.

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.

Wiki is not a end all

[wilkinsm]

(First off, I'm a big TightVNC user and I need to thank you for such an awesome program.)

I think Wiki's are a good way for gathering information - but it is not a total replacement for documentation. Another cool project that uses a free form wiki extremely well is POE (no direct link to protect it), but good consise documentation is still an elusive goal. I've experimented with twiki [twiki.org], which I like alot, but in my workplace I need more controlable structure so I'm going the more formal CMS [cmsinfo.org] route instead. I

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:I think Wiki would be terrible for documentatio

[AlecC]

Do hackers really bother going round scribbling on completely open systems? Most of the totally open Wikis I have seen suffer occasionally from idiots, but rarely from maliciopus damage. There is just no thrill in breaking into something that is not at all protected. Obviously, there may be the occasional idion, but a rollback system, which can identify all the pages altered witin a time window and roll them back to before the attack, should make it relatively trivial to undo. A don't-post-too-fast system (

Re:I think Wiki would be terrible for documentatio

[vericgar]

SquirrelMail uses a wiki on thier site, and I find very little cruft even though anyone can go in and edit any page. Why? Because as soon as someone sees the cruft they remove it. Thus is the power of the wiki.. it self moderates.

php.net

[dpash]

I was always impressed by the documentation on php.net. They have (had?) a copy of the documentation but you could add comments to to bottom of every page so you could add extra information. While this won't help you write the documentation, it would certianly help keep it up to date and help you add, modify or remove areas.

wiki used successfully on cocoon

[stinkyelf]

the wiki [cocoondev.org] that cocoon [apache.org] uses works very well...

Doxygen?

[MattGrounds]

Adequate documentation of code isn't just a problem for open source projects - pretty much everywhere I've worked the documentation tends to be poor unless there is a strong contractual obligation otherwise.

If the documentation is for people contributing code to the project, Doxygen [doxygen.org] is great for generating documentation from your source code, which you can annotate with javadoc-style comments. Great for seeing how convoluted your inheritance trees are becoming.

If the documentation is for people who

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.

Documentation doesn't just happen.

[Big Sean O]

A documentation site that's just a skeleton wiki turned loose to the masses to be created won't happen. The signal will never exceed the frustration of not being able to find what you need.

I imagine a documentation site where the authors wrote a docs and posted them on-line. The public can annotate the docs, posting questions, improvements, clarifications, whatever, at the bottom of each page. I think MySQL does something like this.

The editors would need to sweep these pages regularly, read the annotation

Twiki

[TB]

We've been using Twiki [twiki.org] for 2 years now. Its fantastic and will suit you perfectly. Takes some getting used to but is 100x better than message boards or other forms of community software.

coupla items: Twiki, for one, and ...

[DancingSword]

TWiki [twiki.org] has built-in version-control, so you can recover useful info after the site's been defaced ( if you choose wiki )

Questions, though...

Accessibility: how much?

web-forum is totally accessable, wiki less so.

Do you want whomever can contribute to do so?

I'd use a forum, then, but instead of expecting the forum to produce finished docs, I'd use a moderatable forum to produce raw info ( tips & tricks, experiences, point-up blindnesses in the program's --help listings, etc. ) that could be turne

phpwebnotes

[ubiquitin]

The PHP documentation-comment system is affiliated with a project called PHPWebNotes [sourceforge.net]. Recently I was in a similar situation to the one described in this slashdot post and I looked through about thirty or so different documentation projects in freshmeat.net and hotscripts.com.
I thought phpwebnotes was the best of the bunch, but your mileage may vary.

Compare www.mysql.com/doc/en/index.html

[aminorex]

The bulk of the value in the mysql and php web
documentation is in the user comments (especially true
of the php library functions, which typically have
minimalistic documentation).

Both of these examples would greatly benefit from
the attention of an editor who would periodically
roll the results into the main document. (But be
sure to include a copyright release in the submission
form.) While the current result is suboptimal
in this regard, on both sites, it is still a vast
improvement over the unannotated docume

Virtual Document: Distributed document editing

[vinod]

What is required is a capability to allow document to be "Virtual" i.e. it is picked up from independent editable pages. This is very much like FAQ-O-Matic, but wiki can help in presenting a proper document structure by including different parts of document from different editable pages.

And each editable page may have a section, or couple of sub-sections. It may have owner or may not have owner. But all contributers may have to learn more than typical wiki formatting - to make sure that the document struct

FAQ-O-Matic

[alexpage]

AMANDA [amanda.org] uses a FAQ-O-Matic [amanda.org] which seems to work very well for their purposes. Cetainly something I've considered implementing myself.

An example

[pete-classic]

Check out http://squirrelmail.org [squirrelmail.org].

I think that this is a pretty successful example of what you are trying to do.

It does take some effort on the part of the "core" people to keep it sane. And it is probably less than ideal in terms of organization and not having any "questionable" entries. And it isn't a nice DocBook "1.2.2 Configuring SquirrelMail for your IMAP server" type doc. But it does largely get the job done.

-Peter

PHP docs are a great example.

[cornice]

My favorite docs are at the PHP Site [php.net]. 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.