Using a wiki for documentation isn't a new idea. Countless open source projects do. If you're looking for a way to write and publish documentation quickly, a wiki can be a viable alternative to the many technical writing tools out there.
That said, the documentation on many wikis isn't always as effective as it could be, and you can use some techniques to help you make the documentation on your wiki more effective and more readable. You can use these tips whether you're creating new documentation on a wiki or if you're moving existing documentation to one.
Think outside of the "book"
I've learned one lesson from spending over 20 years in the trenches a technical writer: No one likes reading thick manuals. It doesn't matter if you start off writing documentation on a wiki or move your documentation to a wiki, those wikis can become online versions of thick manuals. Far too often an entire chapter in a manual becomes a single page on a wiki, and that's a lot of text and images for a reader to wade through using a browser.
Remember to move away from the model of the book. Instead, break your documentation into manageable chunks. Effective documentation on a wiki should be a structured collection of those chunks, and not just a big slab of information that's dropped in front of a reader.
You can do that using the principles of "topic-based writing." With topic-based writing, each portion of a document, such as reference material or a procedure, becomes a single wiki page (or a "topic"). For example, the introduction to a chapter is one page, a procedure is another page, and so on. If you have long procedures in your documentation, you can break them into several shorter pages.
You might have short pieces of content like a single-paragraph overview or a one- or two-step procedure. Putting content like that on its own page doesn't make sense. In fact, pages like that look out of place. Instead, keep that content where it is. You'll wind up with a slightly longer wiki page, but that's preferable to having a set of pages that seem like an afterthought.
Navigation is important
Taking a topic-based approach can result in disjointed documentation in which little, if any, continuity between topics exists, but it doesn't have to be that way.
You can get around the disjointed nature of topic-based documentation with proper navigation. Well-thought-out navigation helps readers to move around topics on a wiki easily and quickly and to find any additional information they might need.
What are the elements of good navigation? They include:
- A detailed table of contents that readers can access wherever they are on the wiki
- A set of landing pages containing links to groups of related content (for example, installation and upgrade procedures)
- A set of links at the end of each page that point to related information
Adding links to your wiki pages involves a lot of manual work, but doing so is worthwhile because it makes your reader's experience much smoother.
Looks can matter
Documentation has to have an aesthetic strategy. It has to be friendly, not just in the way it's written, but in the way it presents itself. It should be easy to read, look attractive, and look like something you want to engage with.
—Adam Hyde, co-founder of the Common Knowledge Foundation
Most documentation that appears on a wiki looks like… well, it looks like it's on a wiki. There's nothing wrong with that, but readers expect a bit more, and that means making the wiki itself attractive to readers. It should have the look and feel of your project's website. At the very least, consider using something other than your wiki's default skin.
Nothing says wiki like CamelCase in titles and headings. CamelCase in a page title or a heading is unsightly—it's visually jarring. Instead, add spaces between the words in a page's title or in headings. For example, instead of naming a page "WritingASimpleMacro" name it "Writing a Simple Macro." Adding those spaces goes a long way toward making a wiki page more visually appealing.
One final thought
Wikis can be very flexible and powerful tools for writing and delivering any kind of documentation. Ensuring that the documentation on a wiki is effective takes a bit of work, but that extra effort focuses that the documentation on the needs of your readers and makes it easy to use.
1 Comment