Documentation Done Right

Okay, first, take a look at TimTam’s main page:

http://timtam.codehaus.org/Home.

Now, notice that little Edit link down in the lower right hand corner? Yep, TimTam’s site is powered by a wiki. A wiki, for those who don’t know, is a community edited website. It allows you to edit the content of a webpage online using a form of shorthand markup. Some of the advantages of a wiki include the easy and speed of writing documentation. Since it’s editable by anyone (some wiki’s can require accounts though) anyone can go in and make a change. Used responsibly this means rather rapid and dynamic creation of online documentation. For example, a user fed up with developers ignoring the documentation can go in and update stale information.

However, wiki’s are usually as pretty as “regular” websites. In order to simplify the editing process, you generally do not write wiki content in HTML but in a simplier shorthand markup instead. This somewhat limits the presentation abilities. So wikis are great to write, but not always great to read.

Now, look at TimTam’s site again. Clean presentation. Menus and logos. A nice simple design. How did this happen?

Well, TimTam uses a script that pulls data from their wiki and applies a nice template to get pretty (fast) static HTML. You can see the wiki version of the front page here:

http://docs.codehaus.org/display/TIMTAM/Home

The navigation bar is generated from:

http://docs.codehaus.org/display/TIMTAM/Navigation

This is so cool. The benifits of a wiki with clean site design. No messing with XML markup, no CVS or build systems, no maven or ant or forrest. Just a wiki, a simple script, and wow, you’ve got a nice site.

Now, there are only a couple of other things that would make this truly perfect. Right now the scripts that TimTam uses work with Atlassian Confluence. I would hope it wouldn’t be impossible to write something similar for other wiki’s like MoinMoin.

The other things I might want include:

• A way to have more than one navigation menu, ie- different menus for different parts of the site
• Expandable sidebar menus
• A script that converted the wiki docs into PDF instead of HTML. Nice for tutorials and whitepapers
• An easy way to incorporate externally generated documentation like javadocs and other reports

I’m sure I’ll think of a few more things later. Perhaps there would be a way to use Apache Forrest for this and have the source data be the wiki instead of XML files? That might be overkill, but it keeps the basis of the system the same: the content stays in the easily modified wiki.