Daisy Does Documentation

Documentation is difficult. Design documentation especially so. Traditional documentation tools, like Word and OOo, get in the way: using them is like wearing boxing gloves to build sandcastles. There has to be a better way.

To be useful, design documentation has to:

• be written collaboratively
• have rich internal linking (which doesn't break!)
• have rich external linking (with breakage and change reporting)
• be versioned
• be annotatable, globally and by version
• be machine readable (e.g. in XML)
  

Other factors, like access control, are also important; but I won't be considering them today.

Collaboration used to imply SharePoint or Documentum or Alfresco or whatever. All of which IMO add further layers of complexity to an already over-complicated set of tools. Nor do they satisfy the linking requirements. Versioning is there, metadata is there, but the fact they all deal in de facto proprietary binary file formats, like .doc and .xls, slams the lid on their coffins.

Enter stage right Wiki 2.0, three examples of which I've had a play with.

First found was DekiWiki, the commercial site for which is very slick, and offers a VMWare image as a free trial. Which installed beautifully, but completely failed to send me the email containing its randomly generated admin password.

Next found was XWiki. While not as glittery as DekiWiki, it's stupendously flexible, and has an impressive list of current users. Some videos of it in use are here. I installed the standalone bundle, which, once I'd dug through the web site comments to discover the user 'Admin' password 'admin' (note the case change!) worked as promised, albeit slowly on my mere 1GHz test machine.

I don't doubt that, with a little bit of effort, either DekiWiki or XWiki could be tuned into excellent documentation tools. But there is one that's a 90% solution SOTW.

Daisy. The Flash demos are here. The extensive documentation - written using Daisy - is here.

The only omission is a report on broken and changed external links. Given that the GUI can be extended with JavaScript and/or Java Applets, adding these features shouldn't be too big a problem.

More later. I'm gonna go play :-)