Pros and Cons of Documentation Wikis


You may not have noticed it, but people often get attached to their favorite technology. It can be a mobile phone, a programming language or a text editor. When working on someone else’s project you usually have to use the dominant tools and languages, but when it comes to your own project you choose the toys. Documentation also requires technology, but most people have less of a predefined opinion on documentation tools than they do on web frameworks and version control systems. So how do you choose a project?

Wikis are a popular choice for many open source projects. Here are a few reasons why:

  1. Wikis offer a simple syntax. Contributors need to learn very little markup, and most wikis have a “formatting help” link for tips. Formatting buttons on some wikis can mean zero manual markup.
  2. Wikis do not require any special tools for contributors. All you need is a web browser. It doesn’t matter whether you are working from a desktop or a mobile device. With sufficient motivation, you might even be able to update content with loop.
  3. Some project hosting sites include a wiki as part of the hosted offer. This means that you can jump straight to writing content instead of creating a server, creating the database, etc.
  4. Wikis usually have built-in version control. Need to cancel a change? Just make a few clicks.
  5. Some wiki platforms have “talk” pages, allowing for meta-discussion. This can be a very useful way to discuss content changes in a more constructive way than warring changes.

Make the decision

Wikis aren’t perfect, however. They are not well suited for re-editing in other formats or offline editing. Keeping content organized so that it can be found easily can be a challenge. Unorganized wikis are particularly prone to duplicate and outdated content.

This doesn’t mean that your project shouldn’t use a wiki. If you want contributions from many people, especially less technical contributors, a wiki is a good choice. The Arch Linux project in particular did a great job using a wiki for documentation.

Wikis are well suited to short articles on specific use cases. Someone looking for information on how to push a new git branch to a remote repository will likely find a one paragraph wiki article more accessible than finding the information buried in a 50 page user guide.

Wikis can also be great for rapidly changing content, development planning, for example. If your project is young and has not yet stabilized, writing detailed documentation may not even be possible. The release notes for the Felt The project begins as wiki pages, which are then converted to a rendered markup language, combining the best of both worlds.

The best documentation is what is actually written, so always favor a wiki over no documentation at all. Because the barrier to entry is so low, using a wiki can be a great way to get a lot of content quickly. Just be prepared to take care of the wiki garden.

Doc
Plate

This article is part of the Doc Dish column coordinated by Rikki Endsley. To contribute to this column, submit your story idea or contact us at [email protected]


Sam D. Gomez