Community-Driven Documentation for Free Software? 33
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: (Score:2, Interesting)
Can't beat those for user-based support.
Re:Two words: (Score:2, Funny)
Incidently, the irony of my post hit me about five seconds after I made it...
Wiki's need ratings (Score:5, Insightful)
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 (Score:2)
You mean like Everything 2 [everything2.com]?
LFS (Score:4, Informative)
Need a project outline (Score:3, Insightful)
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 (Score:4, Insightful)
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 (Score:2)
I will say that this is the UI specification, but documentation would be good at it too.
But Seriously (Score:4, Informative)
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 (Score:1)
inefficient? (Score:3, Interesting)
Re:inefficient? (Score:4, Insightful)
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 (Score:1)
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 (Score:2, Insightful)
Re:I think Wiki would be terrible for documentatio (Score:2)
Re:I think Wiki would be terrible for documentatio (Score:1)
php.net (Score:1)
wiki used successfully on cocoon (Score:2, Interesting)
Doxygen? (Score:1)
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 (Score:3, Informative)
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. (Score:2)
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 (Score:1)
coupla items: Twiki, for one, and ... (Score:1)
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 (Score:2)
I thought phpwebnotes was the best of the bunch, but your mileage may vary.
Compare www.mysql.com/doc/en/index.html (Score:2)
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 (Score:1)
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 (Score:1)
An example (Score:2)
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. (Score:3, Insightful)