Tech Explorer

A couple of weeks ago I started a documentation project to write comprehensive documentation for all of the websites that I’ve developed as part of the Flinders University response to the RQF. I wanted to avoid some of the common issues with documentation such as:

1. Multiple versions of the same document.
   How do you ensure everyone has the latest version?
2. Single source of authoritative information.
   How do you ensure the copy they have is the right one?
3. Reducing the amount of duplicated information.
   As a writer, how do you stop yourself writing the same thing more than once?
4. Document accessibility.
   How do you ensure those people who need the documentation can access it?
5. The writing process.
   How do you make writing the documentation as painless as possible?

With these questions in mind I decided I would use a wiki. I’ve used wiki type software for documentation before. While at Adelaide University I used MediaWiki and at the RUBRIC project I used the Wiki built into the Trac open source software.

Having decided on a wiki I needed to track down the right software. There are many different options for wiki software and I started with the Comparison of wiki software on Wikipedia. Wikipedia is arguably the most well known example of a wiki. Looking at the software I had a couple of other requirements. They were:

1. The software needed to be easy to migrate
   I was looking for software that wasn’t tied to a specific database platform
2. I needed to be able to run the software on Ubuntu Linux
   I’ve done all of my development work on a laptop running Ubuntu Linux and didn’t want to change
3. I needed the documentation to be available on a Windows 2003 server
   So it needed to either run on Windows or be able to export into plain HTML

In the end I chose the MoinMoin platform. Although there is a desktop edition of MoinMoin, I went with a full server install. The software is written in the Python programming language and was very easy to setup on my laptop. Installing on the Windows 2003 server was possible but I don’t have sufficient administrative rights to the system. I decided I could use the MoinDump functionality to create static HTML pages.

This was a trial project, and if it is well received we can look at installing a full version on the server if necessary.

It’s been a few weeks since the first version of the documentation went live and so far it has been well received. Using the wiki software has been it very easy to compile the documentation. I’m able to link to pages with common information on them to reduce redundancy.

I don’t use the WYSIWYG editor and use the wiki markup used by MoinMoin and can create pages very quickly. One aspect of technical documentation, especially across more than one website, is that sections repeat. I created basic page templates and fill in the sections with the information specific to the website I’m documenting.

If you’re looking at documenting a project, I would recommend looking into using a Wiki for the project. It makes the whole process much less complicated.