Wikis don’t work for software documentation

This post was originally published on the Doctave.com blog.

If your software documentation lives in a Wiki, it’s very likely out of date and possibly actively harming your engineering team’s productivity. This is a story that repeats in almost every organization — a tool like Confluence or Notion is selected as the “corporate knowledge base” of choice and developers start documenting code in them. But time and again that documentation goes stale and eventually serves no other purpose than to confuse eager new hires.

What are wikis good for?

First, let’s take a look at what wikis do work for. They are used actively by millions of people every day and absolutely have good use cases.

We’d list the following reasons:

• Trivially easy to add new content
• WYSIWYG editing allows non-technical users to collaborate
• Searchability and linking across pages

Wikis are an accessible and easy to use way to write down information. At a click of a button you can create a new page and the powerful in-built editors make it easy to add graphs and style to your thoughts. Finally, once it’s all written down, you can reference other pages and search across the whole knowledge base. Wikis are the lowest common denominator that can work in most cases.

What can’t you do with wikis?

But let’s look at what you cannot do with wikis:

• Integrate documentation changes into code review
• Atomic changes to your docs and code
• Programmatically generate docs at build time
• Edit the documentation using your IDE/editor of choice

Wouldn’t you want to be able to see during code review that the relevant documentation has been updated along with the code? Maybe the committer included a link to the updated wiki page, but are the docs changes already live before the PR is merged? Or will they remember to go submit the changes in the wiki once the code goes live? What if your update only applies to v2.5 of your product but not the newest v3.1 release and the documentation needs an important update?

None of these questions have clear answers when using a wiki and most likely will lead to the documentation simply never being written or maintained.

As Riona MacNamara, who worked on Google’s internal documentation tooling, put it:

Documentation will never be part of engineering culture until it is integrated into the codebase and workflow.

A better tool for the job

We previously wrote about how Google, Twitter, and Spotify all built their own docs-as-code systems for managing internal technical documentation. They did not build wikis.

Instead, they built systems that allowed documentation to live next to source code and get rendered into searchable pages in CI/CD. This practice is generally called “docs-as-code” and is not a new invention.

What they all found was that allowing developers to update documentation as part of their regular workflow lowered the barrier to update docs and ultimately lead to better documented projects. Instead of having to step into a different system to make changes to the project docs, all they had to do was open a Markdown file and start writing. There was one way to document and it was optimized for developers.

Removing friction leads to better documentation. We should be using better tools to remove all the friction we can.

Trade-offs

No solution is perfect, so let’s take a moment to talk about the trade-offs of taking a docs-as-code approach.

Firstly, using docs-as-code will make it more difficult for non-technical collaborators to edit documentation. That being said, for internal technical documentation the maintainers should be the engineers and technical writers. Also, GitHub allows editing directly in the browser, so everyone does not need to learn the correct git incantations to contribute.

Secondly, you have to think about search. If you use a documentation site generator to turn your Markdown docs into HTML sites, even if the toolchain builds a search index for the site, you will end up with N disconnected sites for N projects. Doctave.com can help with this if you are using our open source documentation site generator.

Finally, your documentation will have to be limited to Markdown (or an equivalent format). Many would argue that this is a feature, not a limitation — forcing documentation to be in a simple format can make it easier to write and consume. Some tools will support useful “extensions” to Markdown. Our generator for example supports Mermaid JS diagrams, so that you can embed graphs and charts into your docs easily.

Technology options

Here’s a quick list of some technology options if you want to look into docs-as-code.

We are building Doctave.com to be the best home for your technical documentation. If you want to do docs-as-code with a light-weight open source docs site generator, but host the docs in a centralized place that allows searching across all your projects, check us out.

There are also many open source generators out there that are worth mentioning: MkDocs and Docusaurus to name a couple popular ones. If you need something more customizable, Jekyll and Hugo are good options. Generic static site generators however tend to add a lot of complexity so we’d recommend going for something more light-weight.

In the end, the exact technology choice is less important. As long as it’s not a wiki.