Christian Neukirchen has come up with something original for his forum, Fugi. So what's so original about it? Well, a two-dimensional layout for starters...

Cameron's serenade to Confluence coincides with a recent discussion we had in a project I'm working on. That discussion started in the aftermath of a project retrospective and involved the way we kept all of our project documentation in a wiki. Here's the short version.

We're developing a tool used by other development projects within the client's organization. We've now released 4 versions of the tool since the project's inception on my part, roughly 4 months ago. As a result, the users we go talk to have different versions of our tool installed. Usually they just upgrade to the latest release but sometimes upgrading would be too much of a hassle for them to do right there and then (the reason being that sometimes there are non-backwards compatible changes which require them to also update their working documents to match the version of the tool they're using).

So, what does this have to do with the documentation being in a wiki?

The fundamental problem is that while wikis are great for maintaining live information on a website, they are less great in publishing different versions of that information. In our case, for example, we'd like to be able to "tag" a given version of the wiki with "0.7" and then give our users a URL that points to the front page of the documentation for that specific version. Unfortunately, that's not something most wikis I'm aware of support.

This leaves us with few options. We could just clone all the pages and suffix them with a version number but that's such a horrible thought that I'll just leave it at that. We could also have the system admin clone the whole wiki directory on the server, which could be a decent solution for now if only we could perform the cloning ourselves (we're using an internal corporate wiki hosting service). We could of course just install the wiki software on our own server, which should be quite sufficient except for the backups perhaps.

The versioning issue isn't all there is, however. Even if we could work around the versioning, we'd still be dependent on online documentation and every now and then we're in a place where Internet access is a wet dream (or at least a costly one--more than 10 euros for an hour of Internet access in hotels doesn't surprise me anymore). It would be so much easier if we'd have the correct version of the documentation also distributed along with the tool.

As a result, after a four-month stint at using wiki and wiki only for documentation, we're now looking into tools that would let us work with a simple wiki-style syntax we could store in our Subversion repository and get both online and offline documentation from that single source.

We're currently looking at adopting reST. I'd love to hear your experiences with it or with similar formats/tools.