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.
Phil, we could rename and lock it. The problem is that we'd have to copy-paste the source for all the renamed pages (the majority of the pages' content remains the same--we just do a gazillion small edits between most releases) and that's a bit too much for our taste. That's why we'd need a way to clone the whole wiki, preferably through the web UI.
Some kind of a PDF generation plugin would indeed solve the problem of distributing the documentation with the software. However, with that approach I don't see a way to go back and edit the already released version of documentation--since all we have is the PDF.
The wiki we're currently using is Twiki, by the way.
since all we have is the PDF
er, and the page you generated it from presumably, so you could make changes to that and re-generate the page. I think there are two PDF-plugins for Twiki at the moment.
I think the use of wikis for project and product documentation will only increase so native support for what you're after will almost certainly come (and probably in Confluence first - it really is awesome); as it is, I think TWiki stores its data on the filesystem doesn't it? So you could set up a cron job or some such to check the files into a subversion repository, and you can tag that.
Another option would be to write a plugin which actually does this version tagging for you.
Just switching to reST is no replacement for using a proper collaborative workspace, so I'd perhaps investigate either an alternative wiki or wiki-like system which supports the features you need, or adopt one of the plans above.
Personally, if Twiki has otherwise been satisfactory, I would choose to either write a plugin or store the files in Subversion and tag them directly.
When a page reaches a stable condition for a release, can't you just rename and lock it?
If you need to distribute all or parts of your wiki, run it through a PDF converter (most wikis have this either natively, through plugins or patches).