Confluence Is Where Documentation Goes To Die

The majority of companies I’ve worked at have used Confluence. And the one thing you can be sure of is that any documentation you have written there will be hopelessly out of date.

(This post was originally published on Nik’s personal blog).

Lack of trust

The moment your documentation starts to be out of date, it starts to lose its value. Once developers stop being able to trust that the docs reflect the true state of the world, they’ll stop relying on it, and therefore, stop improving it.

And so the destructive cycle begins.

Out of date documentation can sometimes be even worse than no documentation, leading developers on confusing multi-day expeditions as they try to understand a new codebase.

Source: Geek and Poke

Is there a fix?

The main reason that Confluence ends up being a graveyard for docs is that it is outside the normal software development workflow. Only after the code is merged, do you (if you remember) go to this separate WYSIWYG thing, and decide how to document what you released. This is all backwards.

With that in mind, here are some steps you can take to mitigate the problem:

1. Put your documentation in source control, next to the code it is describing
2. Start asking for documentation updates in pull requests when appropriate, just like you expect tests for new code
3. Create a documentation style guide for your team that sets expectations
   • “Every repo must have a README with x, y, z sections”
   • “Every big architectural decision must be recorded in an ARD“
   • “Every repo needs a high level architecture diagram describing the main data structures and processes”

You don’t write documentation for your present self. You write it for yourself 6-months from now, the new team member joining next week, for your replacement when you move to a new job. Do them all a solid and make their lives easier: write some decent docs and keep them alive.