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.

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.

---

While you're here, if this resonated with you, you might be interested in what I'm working on. Head on over to my personal site if you want to reach out or hear more.

Comments

[Hanokh Aloni]

Cmpletely agree, however there are impediments in legacy systems where migrating the documentaion from confluence to code repo might take too long. Also, when working on many projects you havr to have a good documentation formats.

[Pravin Kumar Damodaran]

Completely agree. Confluence may be a good option for the product management department (those who don't have much to do with writing code or trying out integration tests/demos).

But proper README's are definitely required for devs, and apidocs in case of testers. There's no better place than the VCS to keep them.

[nsouca]

Thanks for the article. Awesome title!

[nnishimura]

Totally agree on this. But we still need to be able to share doc with non-developers - I wonder if there's a better platform with git integration. Netlify CMS?