Like them or not, wikis are becoming more and more common in various enterprises. And they’re not just a developer’s tool anymore. They’re used fairly extensively for documentation, too. The beauty of wikis is that they’re easy to use and that they’re living documents. The content on a wiki is constantly being updated and (you hope) refined.
The dynamic nature of wikis, though, can cause a few headaches when you need to baseline documentation that’s on a wiki to correspond with the release of your product. That’s the problem that we ran into at the firm at which I’m working right now.
Why would you want to baseline a wiki?
There are a number of reasons. If your employer follows ISO or ISO-like processes, then during a quality audit you may need to correlate the information that’s on a wiki with a particular release of a product. Or, you might be subject to some regulatory requirements and need to maintain the digital equivalent of a paper trail.
Whatever your reason for wanting to baseline the documentation on a wiki, there are several ways to go about it.
Use the wiki’s version tracking feature
Any wiki worth anything automatically tracks the history of changes to a page. It keeps a record of changes that were made to a wiki page, broken down by date and the changes that were made on a date. And using the version tracking feature is the easiest way to baseline your content.
If, for example, October 31 version of a wiki page is the baseline, you can go into the history of a page at a later date and view the contents of the page as of October 31. All you need to do it let people know which version is the baseline for which release.
Put the baseline version on its own page, and lock it down
I’m sure that we’ve all sneered more than once at the venerable cut and paste method of doing things. But when it comes to baselining wiki content, copying and pasting can be very simple as well as very effective.
All you need to do is edit the wiki page that you want to baseline and copy all of the text and markup. Then, create a new page and paste what you’ve copied into that new page. Just remember give the new page a unique, though derivative, name. So, if the original page is titled BootFromUsb, call the new page BootFromUsbRelease2.0.
Take a snapshot of the baseline version
Wiki pages are not HTML. They’re plain text files that contain markup. The wiki engine converts those text files to HTML for display in a Web browser. The text files are human readable, and their names are the same as the titles of specific wiki pages — for example, the content of the wiki page RevokingSslCertificates is in a text file named RevokingSslCertificates.
It is quite easy to go into the directory on the wiki server that holds the text files, archive the files, and then move them to another directory on the network. If you need the baselined documentation in the future, you can set up another instance of the wiki and then load the archived text files into that instance.
Convert the baseline version to a different format
As I mentioned earlier, wiki pages are plain text that contain very simple markup. It’s possible to convert wiki markup to a higher-level markup language, like HTML, XML, or LaTeX. If you have a number of files, you can optionally merge them into a single document and convert them to PDF.
A number of wikis have plugins that will export the contents of a page to Word, ODF, or PDF formats. For example, PmWiki has a plugin to convert wiki pages to Word documents. A lot of these plugins are still experimental, and don’t always work. For example, I’ve never had much luck using the OpenOffice Export plugin with DokuWiki.
Have you dealt with this sort of problem? Or is this even a problem? Leave a comment to share your thoughts.