Slashdot Mirror
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."
Message boards.
Can't beat those for user-based support.
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.
"Can of worms? The can is open... the worms are everywhere."
Sorry grammar police, that's "Wikis need ratings", not "Wiki's".
I will go say my Hail Mary's now, or something.
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).
Slashdot: Where people pretend to be twice as smart as they really are by behaving like children.
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.
Have you read my journal today?
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.
Robert Anton Wilson
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...
Repeal the DMCA!
(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, which I like alot, but in my workplace I need more controlable structure so I'm going the more formal CMS route instead. In particular I like webgui, which seems to be a nice balance between total wiki anarchy and stalin-like control. Note however, that I have a particular affinty for Perl language products in this regard.
Sounds like a great idea which will be prone to abuse. An Editor for the final documents would make it very useful and more efficient that TLDP. =\
Pixels keep you awake!
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.
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.
the wiki that cocoon uses works very well...
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 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 use the project, but aren't coders, then I'm a bit more stuck. Basing it around a markup language like HTML or LaTeX would make it easiest to convert into whatever document formats people require, and if it's in HTML you can just publish it on the web for lazy people like me who don't want to download the whole docs.
Matt
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.
Regards, Tobias
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 annotations, and improve the documentation.
You could use a wiki for that as well, but vigilance is even greater. You will need to park somebody on the 'recent changes' page and monitor each change for quality.
In short, writing quality documentation is hard. You can use all types of goodies to make it easier, it still is hard.
My father is a blogger.
We've been using Twiki 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.
TWiki 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 turned, easily, into user-friendly and complete docs.
Others would prefer a more exclusive wiki, to produce more self-consistent docs...
Do you want the docs to stand on their own?
TWiki's got a plugin that creates non-editable web-page versions of the wiki, so you could deploy it behind a .. password block, and give accounts only to whom-you-trust, and have it automatically create web-pages from the wiki your friends create...
Personally, I'd just go with a forum, and every 6 weeks create a new version of each doc ( and have the comments on that version help me create the next version ).
It'd be as inclusive as possible, it'd force me to perceive where I was creating problems for users' comprehension ( my work's assumptions ), I could put source-code up that way for the parts that were annoying me ( to get as many eyes on it as possible ), it'd be ( from the users perspective ) simpler.
I'd zope ( they're down, right now, some sort of proxy eror? ) it just because then their bookmarks would work...
Messages to/for me ( in me journal )
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 (like /., which requires 2 minutes between posts) should also limit damage.
Consciousness is an illusion caused by an excess of self consciousness.
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.
The PHP documentation-comment system is affiliated with a project called PHPWebNotes. 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.
http://tinyurl.com/4ny52
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 documentation.
Make it easy for people to submit their tips,
and provide a useful online kernel of documentation,
and the result is very useful.
-I like my women like I like my tea: green-
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 structure remains intact. And if the wiki tools can ensure document structure compliance by users, we should expect the strategy to result in good document.
As a general remark, the patterns for distributed management of shared information have not yet emerged - in contrast to individual communication tools such as email. Discussion boards are too simple to be useful in this regard; information management is key part of information sharing.
And since people tend to share information more easily in one-to-one emails, we require some good directives to be used during email composition, so that the data can be pushed to shared area. (And how you can format so that it can also be managed, is an interesting challenge.)
-vgk
AMANDA uses a FAQ-O-Matic which seems to work very well for their purposes. Cetainly something I've considered implementing myself.
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.
Check out http://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
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.