Desperately documenting…

It’s high time that I got my act together with regards to documentation. In order to procrastinate a little longer I decided the way to go was to use a Wiki.

This meant I could do the fun stuff: research what Wiki software to use and set it up, before I actually had to do any real work!

“wiki wiki wiki wiki” – Jam On It by Neucleus

I want simple. Simple, simple, simple. Database back–ends, bah, I’m not planning on building a Wikipedia!

It needs:

  • to be light
  • to have a reasonable default look
  • to be extendable
  • to be easy to use (the whole point is not to have to use xhtml)
  • to be quick (duh)
  • and to have an interesting programmatic design (just encase I do want to ‘play’) ;-)

The winner was: Dokuwiki

It was simple to install, simple to set up and simple to use. It just ticked all the boxes. It uses a plain text document back–end so is simple to backup to a USB stick. It is written in PHP with a quite weird styling system (though it does eventually use CSS).

I can limit who can edit the pages so I don’t have to worry about retreating to prior versions of my systems documentation while allowing people who want to work on a project with me access to edit those specs/documents.

I think it will be very useful.

Getting down with documentation

The wiki’s ability to easily throw text on the web was my main reason for using it for my documentation but for a lot of writing a word processor will always be a better bet. Hence I would write it in Open Office ‘Write’ and copy and paste it into the Dokuwiki interface. This worked quite well but still involved a bit of manual reformatting at the wiki end.

Enter the wonderful OOo Dokuwiki macro. This little beau allows you to do your documentation in Write and then reformats it to Dokuwiki style including any tables! You can find the (old) Open Office document here.

Posted on 24/10/06 06:57 PM by Jack Large

Commenting is closed for this article.