Wikis and the Holy Grail of Content Independence

by Tom Johnson on Nov 2, 2009
categories: technical-writing • wikis

If you work in a large corporate environment, you're familiar with restrictions about accessing production servers to make updates or additions to your help content. To touch anything on a production server, you have to go through the change release process, which requires a lot of paperwork and procedural hassle. Almost no project manager sees documentation as important enough to release a new version of the software into production on account of a need to update the help.

And yet, I regularly need to update the help after the application is released. For example, in the previous project I was writing about, the Local Unit Calendar, after release I learned about a bug in production. I received a couple of questions from a user, and the answers weren't in the help. I had an error in the section about changing calendar color. And I needed to add some more instruction in another section.

When I explain to system engineers that I need a server for my help that I can update on the fly, they always ask why. Why can't I just include my help content in the application? However I explain it, the reasoning always comes off sounding like an excuse for not being able to finish my work on time for release.

And yet, I sometimes don't find out about an application until two weeks before the application goes live and needs documentation. Although I need to create video tutorials, the interface isn't frozen until the application goes into hardening and becomes a potential release candidate.

If the materials need to be translated, the Translation department requires at least a month of turnaround time. If the content will be printed and sent out to users, I may have to get the content approved from a department that ensures message consistency.

If subject matter experts don't take time to carefully review the material and video scripts before release, there's a good chance the help will contain some inaccuracies. Project managers and quality assurance engineers rarely have time to review help material the week before a release. If I don't submit the help content to peers for a style review, there's a possibility that typos or inappropriate formatting will also sneak through.

In short, there's a host of reasons why the documentation might need to be updated after the application is released. If I could access the help content and continue to add and adjust it at any time, independent of application releases, it makes documentation less of a time crunch the night before (for example, to finish the video tutorials for the calendar app., I stayed up until 5 a.m. the night before).

The concept of having control over your help content, to update it at any time, is what I'm calling content independence. Establishing content independence in your publishing environment may be a battle that can take years. For example, at a previous job, it took five years to finally convince architecture that we needed and deserved our own independent folder on a production server.

In my current situation, I've pursued publishing routes in infrastructure that would enable on-the-fly updating, but for two years in a row I've come up empty-handed. With wikis, I think I've finally found the holy grail of content independence.

By nature, wikis sidestep the problem of file transfers, because you can always immediately access and update the content through the browser interface. For content outside the interface, such as PDFs, SWF files, or diagrams, which you can't code into wiki syntax, you can still upload the video tutorials through Mediawiki's file upload utility (and probably through a lot of other wiki interfaces as well).

The interface file upload utility gives you a tunnel to production without having to go through change release!

Note: You can't upload every type of file through Mediawiki. HTML files and Javascript files, for example, are usually forbidden file types. Also, the file upload is one at a time, so a traditional webhelp system generated by Flare or RoboHelp wouldn't be uploadable through a wiki's file upload utility. But if you're using a wiki for documentation rather than a static help authoring tool, this isn't an issue anyway.

To enable file uploads in Mediawiki, you have to make a few tweaks to your localsettings.php file. You may have to adjust your settings in the php.ini file too. And if you want to embed your videos, you may want to install a Flash extension. I'll include instructions for doing all this in another post. But basically, despite the drawbacks that wikis involve, they provide you with an invaluable advantage in help authoring: content independence.