A Few Surprises in Using a Wiki for Documentation

Recently I’ve been working on a simple calendar project that uses a wiki for documentation. Although I’ve heard a lot about using wikis for documentation, and have even used them in the past, I ran into a few surprises this time.

1. Authoring directly on a wiki screws up the history of updates.

The way wikis work, every time someone makes an edit, it’s recorded in a history for the page. When I write, I make a lot of little updates here and there, not just within one section, but across multiple sections. I can make 10 updates, apparently, in one minute (or so someone told me, who complained that I was mucking up the revision history). I like to hit Save Page often, especially if I have the whole page in edit mode (Microsoft has taught me well). When I save frequently, the version history becomes somewhat useless, as it just shows my name a million times.

Version history isn't so useful when you use the wiki as an authoring tool

Version history isn't so useful when you use the wiki as an authoring tool

Perhaps the solution is to author on a practice wiki and then transfer finished blocks of text to the production wiki when you’re ready to collaborate with others on the content?

2. The text width is longer than St. Pete beach.

I realize this is probably a setting I could control through a wiki stylesheet, but the default width of text for Mediawiki pages spans about seven or eight miles. This makes it difficult to read.

Wikis are often really wide

Wiki column widths are often really wide

Wikipedia has the same problem with length. The optimal width for a column of text is about 75 characters in length (less, actually).

(Here’s St. Pete beach, by the way. Next week I’m going on vacation to Florida and am definitely strolling down this long beach, which is my favorite. I’ll be thinking of Mediawiki while I walk.)

St. Pete Beach

St. Pete Beach -- photo by Hanny Heim

3. Community members seem more likely to make little edits rather than create entire pages.

Last week I was at WebWorks in Texas, and I asked Anne Gentle why no one has developed a plugin to convert from wikis to a help authoring format. It makes sense that people would collaborate on a wiki, finalize the content, and then export to a more flexible format, right? Anne felt there wasn’t a business case for creating such a plugin. What?

But after working with a wiki on this project, I see what she’s saying. In my situation, members of the community aren’t going to contribute tons of content. I did receive some help from another volunteer in the beginning, and he wrote several small sections. But when I took over the page with major edits, revisions, and other additions, it kind of pushed him away.

Collaborative authoring isn’t so engaging if two people are hacking away at the same page, changing what each other writes. Authoring this way detracts from one’s sense of authorial ownership. Instead, I believe it’s more common for a single author to create the bulk of a page, and then have the community add edits, a few sentences here and there, tips and notes. The baker creates the cake; others add icing. By and large, there’s one baker per page (at least that was the case with my project).

4. Navigation is cumbersome.

Mediawiki organizes the content of each page into table of contents automatically. The table of contents can get somewhat long and cumbersome (even as simple as the content is), if you aren’t paying attention.

Writing in a wiki format forces you to think carefully about the organization of your content. If the page gets too long, you can break it up into multiple pages.

You have to think carefully about the navigation

You have to think carefully about the navigation

The best-practice paradigm of topic-based authoring — authoring content in small chunks that you can manipulate and single source — doesn’t seem to apply to wikis. If you chunk each section as its own page, readers will bounce from page to page to page. It will become a dizzying experience of clicking and clicking.

Perhaps there’s a way to pull in sections from other pages, but I don’t know how to do that yet. Maybe wikis break down when it comes to single sourcing for multiple roles or audiences. Not sure here.

5. Making updates is incredibly simple.

If there’s a major strength to wikis, it’s the ease of making updates. For example, in looking over my local unit calendar help wiki as I wrote this post, I noticed a couple of inaccuracies. I nonchalantly clicked Edit next to those sections and made updates. I absolutely love the ease of updating a wiki.

For people who need to review the content, it’s easy for them to make changes, add comments, and proceed section by section. Don’t underestimate how important this aspect is in the authoring process. I’ve written before about the importance of living documentation — documentation that you update regularly based on user feedback, problems, stories, and other questions. Because a wiki is a live format, you can tap into it at any time and make changes.

On this topic, also see John Hewitt’s excellent post on living documentation and Stewart Mader’s post, Wiki: A More Productive Medium for Living Documents.

6. Wikis are a web format.

Although I wasn’t too enamored with wikis when I started this project, I’ve come to like them more and more. One aspect of wikis that draws me in is the web format. I’ve realized lately that I enjoy web design. A lot. I like working on the web. I like stylesheets and links and jquery effects and layout, navigation — everything.

I realize that authoring in a tool like Flare produces HTML output, which is a web format, but I dislike the static nature of authoring in a help authoring tool and then uploading the content to a file directory to appear in a browser. There’s a disconnect. It doesn’t feel like web authoring, even if it’s published on the web. It’s more like static HTML authoring.

Although I didn’t fallen in love with wikis in the past, the integration with the web may be enough to convert me. Part of my problem with wikis previously was my expectation that users would contribute more. When that expectation wasn’t fulfilled, I wondered why I was using a wiki.

Now I feel differently. For one thing, wikis ensure a separation of help content from application code. This means I can have access to the help even after applications are released. This is something I feel strongly about. Help content should not be packaged with the application code. When help is packaged with application code, these are the results:

  • little or no interaction with the user community.
  • uncorrectable errors that can’t be fixed.
  • a mindset of it’s-released-so-now-I’m-done.
  • no time for translation or video tutorials (because the app isn’t frozen until the week before release).

7. Wikis provide a new language to learn.

Wikis are supposed to be easy to author in, and for the most part, they are. However, they also provide a new syntax and language to learn. That can actually make authoring more fun. For example, look at this little player button in the image below.

Making an image link to a webpage

Making an image link to a webpage

By default, in Mediawiki, images link to themselves (or to a larger picture of the image).  In this case, I needed the player button to link to the video tutorial, not an image of the player button on the file:image page. You would think that making an image link to another page would be easy in wiki syntax, right? Actually, it took me 10 min. to figure this out. Here’s the syntax:


In retrospect, it seems pretty simple. But the link= part I had to dig up.

Concluding thoughts

Strangely, I started this post somewhat antagonistic against wikis, and as I’ve reflected on them, I’m now considering using wikis exclusively. I don’t know what happened, but I like the direction wikis take me. It’s the direction of the web.

By the way, if you have any feedback on how to improve my calendar help wiki, please let me know.

Adobe RobohelpMadcap Flare

By Tom Johnson

I'm a technical writer working for the 41st Parameter in San Jose, California. I'm interested in topics related to technical writing, such as visual communication, API documentation, information architecture, web publishing, JavaScript, front-end design, content strategy, Jekyll, and more. Feel free to contact me with any questions.

  • http://www.sdiglobalsolutions.com Larry Kunz

    This is really good, Tom.

    I’m particularly struck by items 3 & 4. Because people are more likely to contribute little edits rather than whole topics, and because organization is so critical, it would seem that wikis are incompatible with the DITA paradigm of topic-based, reusable writing.

    Yet both wikis and topic-based writing are here to stay. So we need to find a way for them to inhabit the same universe. Are we looking for a tools solution (seems likely), a shift in mindset, or both? I’m not sure yet, but you’ve given me a lot to think about. Thanks!

    • http://idratherbewriting.com Tom

      Larry, thanks for your comment. When I was at the Transalpine conference in Vienna, we talked about the way structured, reusable content models for authoring contrast with the messy, read/write social web that is also trending. It’s an interesting split.

      It depends on your project, obviously, but I think wikis are going to be the way documentation is done in the next ten years, simply because it’s the way of the web.

  • http://www.redakteuse.de Redakteuse

    Hi Tom,
    some of your surprises result from using Mediawiki – other wiki engines are smarter in some cases.

    For example:

    “to pull in sections from other pages” -> possible in TWiki or Confluence.

    “Authoring directly on a wiki screws up the history of updates.” -> if you make changes in TWiki within an hour they are all merged into one revision (but this has downsides, too. For, example, if you do not want to roll back all your changes)

    I’m not very fond of Mediawiki as it is extremely specialized for the Wikipedia purposes. What I really miss is the option to build hierarchies – not necessary for Wikipedia, for example. So far I had good experience with using Dokuwiki. It offers a lot more possibilities for documentation.

    I also experienced that most people hesitate to edit or correct pages that others created. Only real wiki fans “dare” to do so.

    • http://idratherbewriting.com Tom

      Redakteuse, thanks for your addition to the conversation here. I’m still learning Mediawiki, so I may discover a plugin or other technique that allows me to single source a little more. For example, you can create a Template that you then reuse similar to a php include in pages. I wasn’t aware of that. It only works for little snippets, though.

      Re hierarchies, I’m not really sure what you mean. Can you expand on it?

      with near 100 different wiki engines, it’s hard to know which to use. Obviously Wikipedia is a strong selling point for Mediawiki. I do like how robust Mediawiki is. There are hundreds of plugins for it and abundant tutorials/instruction.

  • http://blog.lauralemay.com Laura

    “screws up history of updates” — I’ve never used mediawiki, but in Twiki and Confluence there’s a checkbox option when you save a page not to record it as a change in the revision history. I use this option when I make a zillion tiny changes.

    • http://idratherbewriting.com Tom

      Laura, thanks for the tip. I’ll look more in Mediawiki to see if I’m missing something. There is a check box for a minor edit, but it still adds an entry to the page history.

  • http://mrscripter.com Brett Johnson

    Agree with comments about media wiki not really being the correct wiki in the case of documentation.

    I think there is common ground between DITA and wikis, but it must be in a wiki that better supports navigation and hierarchy.

    At IBM, it is often our translation processes and requirements that make using wikis or other web apps difficult for us to consider.

    By the way, your posts read pretty well from an iPhone.

    • http://idratherbewriting.com Tom

      Brett, thanks for the note about my posts reading well from an iPhone. I’m using a plugin to help mobile web display. I myself often read blog content from my mobile device, and sites that aren’t optimized for mobile display are tough to read.

      Can you elaborate on the common ground between DITA and wikis? I’m not entirely seeing the overlap.

      Re translation, Wikipedia translates their content into numerous other languages. Maybe Mediawiki handles translation well, even as it handles documentation poorly? Thanks for your comment.

  • http://www.rachelhpeters.com Rachel

    Great article Tom! Makes me want to rewrite my product’s help in a wiki. One day maybe…

    I use TWiki as well (for internal company wiki) and agree with the previous comments. I wanted to add though that I’ve had a hard time with searching on TWiki. Search results are listed alphabetically (instead of by relevance) and the search engine doesn’t offer many options (like best bet results, or sorting by date, etc.).

    How well the search works would be one of my main concerns when using a wiki for documentation. However, if you build a decent TOC for people, you can get around problems with searching (which is what we’ve done with our wiki). But it bugs me that the TOC is all we have.

    That being said, TWiki has a pretty active developer community who is publishing new plugins all the time. Another important point when you explore the world of wikis.

    Thanks for linking to your example. It really helps to see this process in action.

    • http://idratherbewriting.com Tom

      Rachel, thanks for your comment and note about Twiki. I’ve heard good things about Twiki from numerous people. Re search, alphabetical listing of the results seems odd. With Mediawiki, I’m not so impressed with the search, but you can add a parameter in the search (e.g., “Category:Printing ink cartridges”) or something to limit the research results to a specific category. (The results are by relevance not by alphabet, at least.) Of course that might be beyond most users.

      Thanks for the heads up on search. I’ll have to address it in my documentation strategy somehow.

  • Amalia

    Hi Tom,
    We’ve been using MediaWiki for our internal communications and for developing/publishing our product documentation.

    Some thoughts…
    1. “Authoring directly on a wiki screws up the history of updates.”
    Suggestion…At the start of each software release, why not export the latest revision and import into a fresh, clean new wiki? We do this for every major software release for our online version (for customers).

    2. “The text width is longer than St. Pete beach.”
    This can be easily controlled by a style sheet for any of your Namespaces. We do this especially for lines of code in the examples we provide.

    3. “Community members seem more likely to make little edits rather than create entire pages.”
    The good thing about this is that everyone has become aware of how very easy it is to make a small update…any minor correction. Our developers no longer have to take the time to create a doc bug in our system or send me email. They just click the “Edit” tab, and voila! the change is made.
    Plus, we use a template at the top of each wiki page (in our internal “production” wiki for product documentation) that provides a rating system. Our developers can see at a glance in our wiki dashboard which pages have a higher rating (because of the number/type of examples, interface descriptions, images including Flash, etc.). Some of our short, outdated pages have been greatly transformed! And because the system is so easy to use, developers have created new pages. (I provide boilerplates to make creating new pages easy for them.)

    4. “Navigation is cumbersome.”
    You gotta use categories and sub-categories! Plus you can do away with the TOC on any page (or group of pages as in a Namespace) if desired. We use templates so that an auto-generated TOC can be displayed either in our Portals, Release Notes, or any place where we want to provide extra navigation. Using Categories has been essential…plus it provides a “bird’s eye” view of the entire site’s contents when you expand on any of the Category trees.
    I do agree with you that creating short pages is best. We make use of See Also and NavForward links at the bottom of our pages, especially in our Tutorial pages.
    And yes, there is a way to pull in sections from other pages…transclude. Or use the NAVCONTENT plugin.

    5. “Making updates is incredibly simple.”
    Yes, absolutely! That’s the beauty of a wiki!

    6. “Wikis are a web format.”
    Ah! But they are living documents!
    a. “little or no interaction with the user community”
    I disagree. We encourage our customers to post comments, feedback, and doc requests on the Talk (writable discussion) pages. (Each wiki page has a Discussion tab at the top for customer input.) I check every morning for feedback…I let them know that their request has been received and forwarded, and by day-end, I usually have an answer for them direct from our development team.
    Plus, with the latest version of MediaWiki, you can specify in the LocalSettings.php which Namespaces can go unprotected (writable). And you can always create custom Namespaces.
    b. “uncorrectable errors that can’t be fixed”
    Our customers point out errors, and once verified, I fix them immediately…that same day. No need to regenerate HTML files or PDFs. Whatever change I make on the external wiki, I am sure to make the same in our production version (which will eventually replace the external one upon a major release). I also upload all Service Pack changes by tagging them on the production wiki. And with one button, MediaWiki exports all those pages (using a Service Pack Release category).
    c. “a mindset of it’s-released-so-now-I’m-done.”
    Again, try using the template rating system. Provide a dashboard to stir up some friendly competition.
    d. “no time for translation or video tutorials”
    Why not upload the video tutorials or changed pages within a few days post release? (Treat the updates like a Service Pack release.)

    7. “Wikis provide a new language to learn.”
    You’re right. And as you mentioned, “fun”! You can use templates (for example, Note, Important, etc.) instead of styles (via menus, buttons). Editing in MediaWiki is almost as easy as typing in Notepad.

    As you can tell, I’m really passionate about developing and publishing product documentation on the wiki platform. I’ve used everything from FrameMaker, WebWorks, PageMaker, QuarkXpress, Word, and even vi on a mainframe system. This system is truly a collaborative one and saves so much time!

  • Pingback: DITA as a wiki format? « Brett Johnson()

  • http://www.vanarsdall-infodesign.com Eddie VanArsdall

    Tom, I used MediaWiki to write all of the help information at http://biomedgt.nci.nih.gov/wiki/index.php/Main_Page. I enjoyed it for many of the reasons you discuss.

    Like you, I prefer working directly on the web (though I don’t often have the opportunity). Instead of focusing on tools, you can focus on developing quality information. I appreciated the ease and immediacy of updating sections. And if others working on the wiki wanted to edit my topics, they could easily do so.

    Disclaimer: I haven’t been a part of the BiomedGT project for a while, and I note that some of the links aren’t working. I claim no responsibility for that. :-)

    When I wanted to reuse content in topics, I used transclusion. In fact, I wrote a post describing how to use transclusion:



  • Pingback: Technical writers, web writers, jobs, and employers | just write click()

  • Pingback: Using blogs in the documenation process « The Liner Notes()

  • http://ginafromtampa.wordpress.com/ Gina Fevrier


    Do you have any recommendations forf an ISP that can host a confluence wiki (just a small personal one of 10 users). We have a trial at work, but I’d like to have my own wiki on my personal Web site. However, it’s hosted by Network Solutions, and someone on the user forum said it has to be programmed in PHP, and Confluence is Java. (Support hasn’t responded yet.) It’s making me want to switch my ISP. I imagine you were able to get the free version of Confluence because you may have used it for a non-profit organization and they probably had their own server.