Hurdles and Hardships using Wikis for Technical Documentation

After a Q&A on the Facebook discussion page for my book, Sarah Maddox and I had an additional email exchange talking about the difficulties people face when using wikis for documentation.

I believe that many wikis are in the range of “content management systems” or moving in that direction. But there are many difficulties in general with content management. Here are some areas I’ve heard from fellow technical writers:

Access control: Without being able to say who can view or edit what, some wikis are impossible to apply to tech doc due to serving specific business reasons with the content. A customer support article should not be subjected to multiple edits from wiki spammers.

Hierarchy: Without at least 2 levels of hierarchy, tech writers are stymied as to how to use a wiki without hierarchy. Of course. We have complex documentation sets to maintain and hierarchy is a natural way to organize topics.

Version control: The difficulty in maintaining or tracking several versions of a bunch of topics (or an entire namespace/space) to correlate with a software release version is frustrating to many – I’ve heard this is a basic problem for WordPress’s Codex.

Global search and replace – and don’t forget spell check: Writers are used to maintaining giant Framemaker docs where they could spell check and search and replace across large amounts of content. CMSes and wikis don’t make that so easy as before.

Search on the site itself: We’ve all become so spoiled by Google’s search algorithms that any local search engine usually comes up short.

Workflow: Wikis can be weak in workflow, even as simple as “approve or reject” a particular article.

Creating collections: More than just outputting to PDF, people want to single source from a wiki to create collections of articles based on tags, categories, labels, and so on.

Offline access: Many wikis think they’re the end destination for readers, but the classic scenario is “what do my readers do if they need to get on a plane?” One clever solution to this problem would be to offer the wiki on a USB stick – call it a wikiscicle.

Round tripping: Writers are always talking about roundtripping content. I’ve usually dismissed it as not worth the trouble – there wouldn’t be enough contributions that a team of writers couldn’t keep up with. I’ve finally heard a decent business case for doing so – from structured XML (DITA) contained in a CMS to wiki and back again. Translation (to 22 languages) and volume of edits or contributions are the key to this scenario.

One-click publishing (batch processing): On release day, you want to set all topics to released at once, but with many wikis, you have to go to each page one-at-a-time to click them over to the right state for release.

With plugins and advanced wiki engines, these hurdles are easily overcome. But Mediawiki, a popular wiki engine, flunks the first two tests that many technical writers would apply. These are the examples I’ve seen and some of what Sarah has experienced. How does it match up with your viewpoint?


  • March 31, 2010 - 2:38 pm | Permalink

    Like anything else, you need to use the right tool for the right job.

    I think it is pretty obvious that Mediawiki (despite its huge popularity and install base) is *not* the right tool for technical documentation. Tools like WikiMatrix can help find the right wiki.

    “If the only tool you have is a hammer, everything looks like a nail.”

  • March 31, 2010 - 9:48 pm | Permalink

    Think about wikis and what Hugh McLeod says here about corporate blogging.

    (…but not yet having read the Conversation and Community book, I have no idea whether you’ve already gone there.)

    Hugh’s take seems to me to be primarily from a marketing standpoint, but I can see parallels to a knowledge/support angle as well.

  • March 31, 2010 - 10:20 pm | Permalink

    Hallo Anne

    Thanks so much for writing this up! It’s a very interesting topic, especially for those of us who are in the thick of things already, writing and publishing our documentation on a wiki. I’m a notorious wiki hugger ๐Ÿ˜‰ but of course there are things we need to work around too. I think Rick hit the nail on the head (ahem) when he said you need the right tool for the job.

    I have a very good knowledge of Confluence, because that’s the tool we use almost exclusively. Here are a few comments relating to each of you points.

    Access control: Like all your points, this one is a cannot-do-without. Confluence is pretty good. You can set permissions at three levels (site, space and page). You can assign permissions to individual users, groups of users and “anonymous” users i.e. people who have not logged in. You can choose to allow read and/or edit permissions for each person or group. At space level, you can differentiate the permissions for pages, comments, blog postts, attachments and so on. We use these permissions extensively, both to determine who can view/edit a particular space (library) or page, and to hide a page from general viewing while it’s in draft state.

    Hierarchy: Many people argue quite convincingly that content in a wiki should be “flat” and not hierarchically organised. I still think it’s essential to be able to organise technical documentation into logical chapters, and into a specific sequence. In fact, we technical writers have won a bit of a battle here, in that confluence now has a “Documentation” theme with a built-in table of contents.

    Version control: This one is complex. Our wiki tracks versions for each page, but as you say we also need to track a collection of versions related to a product release. We use Confluence “spaces” quite effectively. A space is a logical collection of pages, a bit like a library. But the process of archiving a space and publishing the new release is very manual, and thus time-consuming and error–prone. This relates to your point about one-click publishing. Oh for a button that says “Publish”!

    Global search and replace: Oh yes please!

    Search on the site itself: People do find that the wiki search lacks precision. I’m usually happy with it. One gripe I have is that if you reuse content, the search will pick up the content from the original location but not from the location where it’s reused. The search finds the content in the database, rather than on the rendered page.

    Workflow: We don’t really miss this aspect. Many people need workflow more than we do, and they use the plugins: Theres an Approvals Workflow plugin, a Content Publishing plugin and a TaskDock plugin for Confluence.

    Creating collections: That’s an interesting one! You can tag pages by adding labels, which you can then use to create lists of pages within the wiki itself. I hadn’t thought about using the labels to generate PDF documents. I don’t know if there’s a plugin that will do this.

    Offline access: Ha ha. Notepad? ๐Ÿ˜‰

    Roundtripping: I’m not sure that it will ever be possible or advisable to write your content in one tool, push it through to a wiki and allow edits, and then push the edited content back to the original tool, again and again. With any conversion, no matter how mature and sophisticated, you will lose a certain amount of quality. (Are there any other tools where this is done, i.e. if we swap “wiki” with something else, does roundtripping work?) If we want to edit our core content in the wiki, then I think the wiki should be the primary content repository. At the moment, that’s not possible for a number of scenarios where people need the power that DITA provides for content reuse. So either we need to improve the way wikis handle content reuse and exporting to various formats, or we need to treat the wiki as one of the end formats for the documentation rather than the primary editing tool. In this last scenario, we would use permissions to separate the “official” product documentation (generated from DITA for example) from the community-contributed documentation. The product documentation spaces could allow customers to comment on pages, but not add or update pages. This would ensure that their contributions are not lost when they update the wiki from the DITA source.

    I’d love to hear what other people have to say about other wikis.

  • March 31, 2010 - 10:35 pm | Permalink

    One key issue, which will be answered differently by different groups with different needs, is whether the wiki should be a source format or a target format. Do you maintain your source elsewhere, and publish to the wiki, with or without some form of round-tripping for changes make on the wiki? Or do you maintain the source in the wiki, and publish to other formats such as PDF? If the source is in the wiki, is that really the most effective authoring environment? (C.f. the Mifos folks authoring in a word processor, and then uploading to FLOSS Manuals.)

  • April 2, 2010 - 12:55 pm | Permalink

    Completely agree that the porous membrane is important… thanks for pointing that one out. Love Hugh’s work. Janet’s point that you’ll answer it differently depending on your business needs is at the heart of whether a porous membrane gets you where you want to go. Thanks all for the comments!

  • April 2, 2010 - 1:05 pm | Permalink

    As a tech writer who’s already maintaining documentation in a wiki, another problem I’ve run into (with our specific flavor of wiki — TWiki) is the rigid navigation rules. TWiki loves “WikiWords” – so much so that it automatically formats breadcrumbs that way, and wants links formatted that way as well. Never mind that WikiWords are pretty unintuitive navigation tools for users!

    We also have issues with workflow, offline access, and creating collections. I do like TWiki’s version control though; it’s very useful.

    I’m intrigued by Sarah’s mention of Confluence – I need to check it out.

    Thanks for the post!

  • Kermani
    April 8, 2010 - 3:18 pm | Permalink

    Does anyone here have any experience creating context-sensitive help content with a Confluence WIKI?

  • Pingback:   Weekly links roundup by Communications from DMN

  • April 9, 2010 - 7:57 am | Permalink

    Lisa Dyer at Lombardi (now IBM) has implemented topic-level help in a Confluence wiki. These same concepts should work for any wiki, though. Here’s a slideshow talking about their model.
    You’d need more engineering work if you want to do snippet-level help, and some engineering work if you just want to refer the context-sensitive help to a URL. Like other context-sensitive help implementations, it’s a matter of matching up a list of URLs to an alias that the product can refer to.

  • Kermani
    April 9, 2010 - 10:57 am | Permalink

    Thanks, Anne, This is helpful. However we don’t have a help authoring tool so our team is looking to do this within the wiki sans robohelp, etc.

  • April 16, 2010 - 12:36 am | Permalink

    These are great insights at so many levels, Anne and Sarah. My own work with the literal instance of a collaborative DITA wiki exposed several key things, especially this case:

    Ease of writing is always a concern for content creators who haven’t bought into structured writing principles. While a simplified topic can approach the same level of content model that most wikis support anyway, the proclivities of a schema-directed editor can still make the experience unnerving until the writer internalizes and embraces what they can do with the ability to select whole containers at a touch, for example.

    Countering that, the business decision to try to support structured writing through a wiki may outweigh those issues. My work with the IBM DITA Wiki was based on lowering the cost of transforms and the coaching overhead usually needed to manage style abuse in word processors. Ready publishing in standard DITA PDF workflows is another business imperative that might require writers to just get with the structured writing program.

    In my mind, usability is the across-the-board hurdle for most of the technical issues; training and community support is the best panacea for the meantime.

  • April 23, 2010 - 3:51 pm | Permalink

    Great article! Lots to think about.

    BTW, I linked to your blog in my recent article about where to communicate with technical communicators:

  • Kermani
    May 11, 2010 - 1:27 pm | Permalink

    I’m just getting started with Confluence wiki and I’d like to know if there’s an easy way to insert images into text. I’ve tried using the image link a few times and the end result is not really “whatyouseeiswhatyouget’. I’d appreciate any sugggestions you can offer.

  • Pingback: Even more technical documentation wikis | Just Write Click

  • August 9, 2010 - 3:36 pm | Permalink

    One item not mentioned is that some technical documentation is actually compiled, at the time it is generated, to ensure that the code samples continue to function and are valid. This would be extremely difficult to reproduce with a wiki.

  • September 13, 2010 - 2:01 am | Permalink
  • John
    May 14, 2011 - 12:17 pm | Permalink

    Very good remark about spell check. Spell checkers nowadays are built in many web-browsers, so it is silly to see the misspelled content. If your browser doesn’t support you can always use one of online spell checkers, there are plenty of them, for example this one:

  • Leave a Reply