Wikis and the Holy Grail of Content Independence

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).

Mediawiki's file upload utility

Mediawiki's file upload utility

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.

Adobe RobohelpMadcap Flare

This entry was posted in general, wikis on by .

By Tom Johnson

I'm a technical writer working for the 41st Parameter in San Jose, California. I'm primarily interested in topics related to technical writing, such as visual communication (video tutorials, illustrations), findability (organization, information architecture), API documentation (code examples, programming), and web publishing (web platforms, interactivity) -- pretty much everything related to technical writing. If you're trying to keep up to date about the field of technical communication, subscribe to my blog either by RSS, email, or another method. To learn more about me, see my About page. You can also contact me if you have questions.

10 thoughts on “Wikis and the Holy Grail of Content Independence

  1. Ellis Pratt

    Perhaps you’re talking about publishing independence. If so, it’s worth bearing in mind you could also use Floss Manuals to publish content or even Microsoft Office Live, if you wanted to publish maintainable printable manuals.

  2. Rengaraman

    Good post Tom. Documentation is the least cared area for any project managers I believe. I may be wrong.

    I am really curious to know what will happen if at least one time, some product gets shipped without any help content or documentation. What will be the customers’ reaction..? :)

    1. Jeff

      I just read about a product that shipped without documentation – it’s called Fitbit, and in multiple reviews the reviewers complained that they couldn’t figure out how to use it and that there was no documentation.

      See http://www.engadget.com/2009/10/15/fitbit-review/ for example.

      Excerpt: “…shame that wasn’t in the manual. That’s because no manual comes with the thing, the implication being you just throw it on and go to town. Again that’s not quite the reality, especially when it comes to sleep.”

      1. Tom

        Jeff, thanks for the comment. It always amazes me to see products without documentation. If they had coded their help link to point to an independent site, they could correct their oversight and add help content based on user needs. With web apps, that’s usually not so hard. But with local apps that users download, it’s not an easy fix.

  3. Pingback: Scott Nesbitt (scottnesbitt) 's status on Tuesday, 03-Nov-09 13:04:01 UTC - Identi.ca

  4. Jackson

    The discussion here reminds me of two fairly recent pieces: on Saul Carliner establishing the importance of a department and another in a recent Infocom on paying for the manual. Does Fitbit charge extra for one, or is there none at all?

  5. Pingback: Technical writers, web writers, jobs, and employers | just write click

  6. Pingback: How Microsoft Visual Studio Is Doing Help | I'd Rather Be Writing

Comments are closed.