Your code lives in version control, with easy branching, reviewed changes, and tests, right?
Does your documentation?
Wikis are great for providing a low technical barrier to change. Click, type, save, live!
That’s great in the early days of documentation. You’re starting from zero and your main contributors are probably the pioneers who built the thing they’re documenting. Just like you might not bother with review and testing when you’re first starting to write some code.
But time passes and things mature. The work becomes more about updating what already exists, and less about writing new things from scratch.
At this point, editing a wiki starts to feel like live-editing files on a production server. From a purely technical perspective, it’s very accessible - open up your editor and have at it. Realistically, you need to either be brave, foolhardy, or intimately familiar with what you’re doing.
So how about you start treating your documentation with the same care you treat your codebase:
- Disallow direct edits
- Support a review-based workflow
- Test the bits you can.
Sure, there’s a bit more work involved in making a change, but you’ve introduced guard rails that let everyone move faster.
Less haste, more speed.
But what about Wikipedia
Yes Wikipedia is a wiki.
Wikipedia aims to be a non-authoritative source that the world can contribute to.
You’d probably like your documentation to be authoritative. You probably have a smaller set of contributors.
So what then?
I like to write rST, compiled to a website by Sphinx, stored in Git on GitHub, tested by CircleCI, and published to ReadTheDocs or Netlify or GitHub Pages.
- Sphinx checks that internal links are valid - especially great if you move pages
- Git and GitHub are my go-to for version control and hosted repositories and good code review
- CircleCI to test that the documentation builds for each PR
- ReadTheDocs or Netlify or GitHub Pages because they offer high-quality, excellent value, static hosting
Fin
But documentation is rarely something you just write once and it’s done forever. Make sure your tooling helps you manage change too.