Interregional Software Development Week, Day 5: Documentation

There's something that I like to call the documentation paradox: if there's something that developers don't like doing it's documentation. Yet, if there's something that developers need, it's exactly that: documentation. This is, or at least sounds like, a paradox because it reasons from the developers seen as a group, and that's exactly where the problem lies: we're dealing with a group of individuals. An individual developer has no interest in documenting his or her own piece of code; they understand it, they know their code reads like literature, so why document it? Others have to document their piles of crappy code for it to make any sense, but not them. It would've been nice to, en passant, give a solution to this problem, but the margin is just too small to contain, as "Fermat would say":http://en.wikipedia.org/wiki/Fermat%27s_last_theorem.

Instead I'll focus on a tool that lowers the barrier of actually documenting something as much as possible. This tool is a wiki. Wikis are relatively new and its applications still have to be explored, but I think software documentation can very well be one of them.

What is a wiki again? 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 (who has access to it) can edit. At each page there's a "Edit" button using which you can change the content of that particular page. Wiki pages are written in Wiki-codes, which I briefly discussed "a while 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.

Wikis also have version control, just like the version control systems that I talked about yesterday, therefore you can see exactly who changed what pages and revert to older versions if necessary. Most wikis can also merge changes, if pages are editted simultaneously.

There are many wikis around already. The biggest one (with now over 1 million pages) is "WikiPedia":http://www.wikipedia.org, it 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 as well: "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.

That all sounds very cool, but what should it used for? I think it can be best used as a central information dump. I think wikis would be a good place to store information such as * design decissions (in the architecture phase, "we had to choose between single-threaded and multi-threaded and we chose ... because ...") * programming problems and their solutions ("On several places we needed this very weird sort function. I implemented this function and put it in this and this library")

If you have to do some research, for example to figure out which architectural pattern you should use to solve some problem, you can just dump any information you find on the subject in there. The formatting and structure doesn't matter at first, you (or anybody else for that matter) can tidy up things later. The important thing is that write down problems that you found and how you solved them. If forum discussions took place about certain problems, just copy that discussion in the wiki as well. It's a central storage of thoughts, problems and decissions that every team member can find and store information on.

Personally I haven't used wikis in interregional software projects yet, but I still think it's an interesting area to explore. If you start your project, just think about what wikis have to offer and how you can use them in your project.