A Few Surprises in Using a Wiki for Documentation

by Tom Johnson on Oct 29, 2009
categories: technical-writing • web-design • wikis

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.

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.

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

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.

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.

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:

[[File:Videoplayer.jpg|link=http://lds.netdimensions.com/ldslive/nd/fresco/repository/html/luc/subscribetoacalendar.html]]

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.