There are two things which are particulary not fun about developing software: testing and documenting. The advantage of developing open source software is that finding volunteer testers often isn’t a problem. And although you probably could get away with no documentation at all, it would be nice if there was some of that too.
“Oh, I love your product! I think it’s so great that it’s free and I just wish I could help out. But I can’t program, so I just drew you a new logo.”
When I still developed “YaBB”:http://www.yabbforum.com, we used to get a lot of those (probably still). But honestly, if they weren’t programmers, how could they help out? Some people used our product so much that they started helping other people out installing it. That’s great. After a while, even FAQs popped up, with most common problems and how to solve them. That worked fairly well, but it would be nicer if we could collaboratively expand these FAQs. Letting more people add and correct stuff.
Only recently (a year or three late) it struck me. Wikis are ideal for this!
First some background information. What is a Wiki? To start off, officially they’re called Wiki wikis, which is Hawaiian for “Quick quick”, if I’m correct. But for convenience, and because “Wiki wiki” is impossible to market, people usually abbreviate it to just Wiki. Wikis are a bunch of linked, unstructured webpages that everyone can edit. At the bottom of each page there’s a “Edit” link using which you can change the content of that particular page. Wiki pages are written in Wiki-codes, which I briefly discussed “a couple of days ago”:http://www.zefhemel.com/archives/2004/09/20/post-formatting. So you don’t need to know HTML or something to contribute. It is extremely simple to add pages and to link to them.
You’d think Wikis are easy to sabotage, and they are. The trick is that a change log is held for each page. That means that a moderator can retrieve an older (non-sabotaged) version of a particular page in a click. Many Wikis allow some pages to be locked (for example your front page), so that they cannot be editted (except by moderators). It’s important that there are plenty of people keeping track of changes to the different pages all the time, just to be sure that no invalid data is entered. Usually Wiki software has a global “Recent changes” feature just for that.
There are many Wikis around already. The biggest one (with now over 1 million pages) is “WikiPedia”:http://www.wikipedia.org, which is a free encyclopedia which anybody can make changes to. The very first one, the one started by Wiki’s inventor (Ward Cunningham, now working for Microsoft), is quite big aswell: “c2.com wiki”:http://c2.com/cgi/wiki. There is some kind of Wiki software in nearly every language these days. Ranging from Ruby to C# and from Java to PHP. I’ve some experience with “PhpWiki”:http://phpwiki.sf.net and “MediaWiki”:http://www.mediawiki.org (which is the same on WikiPedia uses). “Here’s a list of other ones”:http://c2.com/cgi/wiki?WikiEngines.
If you set up a Wiki for your open source product and for example place your installation manual and other documentation in there, everybody will be able to make contributions. If they had a problem during installation and found a fix, they can write about it on this centralized piece of documentation. Many people know more than one and many pairs of eyes see more errors than just one. That’s the power of open source software, and Wikis are a great way to apply that same concept to documentation.
So, if you’re developing an open source product, give it some thought.