What about wikis - Specifics

Modern technical writing - Andrew Etter 2016

What about wikis
Specifics

Admittedly, a wiki is simpler than the system I just described. Anyone can figure out how to edit a wiki, which is a killer feature until it isn't. Wikis have huge benefits and huge drawbacks. They certainly have a place in technical writing, but you should think carefully before selecting one.

Users don't need to install any applications, clone any repositories, or learn any strange workflows to contribute to a wiki. They can spot an issue, click Edit, and fix it within ten seconds. The process is remarkable. Also, every major wiki has out of the box search, a huge improvement over most static site generators.

One major problem, however, is that wikis are web applications. If you decide to create and host one, they require maintenance over time. And if you've ever worked at a company with an internal wiki, you know how often they crash or slow down. Yes, Wikipedia has proven that wikis can scale to a huge number of users with good reliability, but that scaling is the result of a ton of hard work from some very smart people, people whose job it is to manage the site. Personally, I want to spend the smallest possible percentage of my time managing a site. I'd rather test, research, write, and curate content. Static sites are indisputably simpler to manage.

To be blunt, writing on a wiki sucks. Mercifully, some wikis use lightweight markup, but it is often a mangled form that incorporates a subset of HTML tags and barely qualifies as "lightweight." Others use a WYSIWYG editor, so the experience is like using Microsoft Word without all the convenient keyboard shortcuts. Everything in a web browser is so ephemeral, ready to be flushed at any time. I've lost at least a few pages of work to connectivity issues and Firefox crashes. Writing lightweight markup in a text editor is faster, easier, and safer. GitHub wikis, which I mentioned earlier, are an exception to this rule (and several others in this section).

Wikis are fantastic for living documents that grow over time and never need to be marked as belonging to a particular software version. Many software as a service applications fit this description. Supporting multiple versions of your documentation—for example, version 3.1 and 3.2—is trivial with distributed version control. Doing the same on most wikis requires specialized plugins and some manual shuffling of content.

Version control systems like Git do an amazing job tracking changes over time. You can view the change log for individual files, easily "blame" others for problematic content, see related changes that have been lumped into commits, and merge disparate commits easily. With most wiki software, you can only view the change log for individual pages. Pull requests in distributed version control serve as a built-in review process for changes. Because most wikis follow the "last person to edit wins" policy, you might not even notice a destructive change to the documentation. Wikipedia ameliorates this problem with a sophisticated anti-vandalism bot that uses machine learning to improve over time. Given my expected lifespan, I'm confident that I could never create such a bot. Your mileage may vary.

Ever gotten work done from a plane, train, park, or hipster coffee shop that refuses to offer wireless internet access? Not with a wiki, you haven't. With distributed version control and static site generators, you have everything you need to write, build, and review changes locally. When you have connectivity again, you can push your changes and update the website.

In short, for a wiki to make sense, your documentation should be uncontroversial and never need to be versioned. You also shouldn't mind writing in an inferior editor, only working online, and maintaining a piece of enterprise software.

1. As of September 2015.↩

2. Source: conjecture.↩

3. The default "grid tables" are horrifying, but CSV tables and list tables work well.↩

4. Please don't call them hyperlinks.↩

5. Aside from the server itself, anyway.↩

6. Number reported, severity of each reported bug, average time to resolve, etc.↩

7. Translation memory can only help so much.↩

8. Or Golden Week in Japan, etc.↩

9. And probably shouldn't.↩

10. To show you how impressed they are, IT builds you a Linux VM with 256 MB of RAM and 3 GB of disk space and refuses to give you superuser privileges.↩

11. But they still don't submit the pull request.↩