Nobody gets excited about documentation. It’s the broccoli of the business world — everyone knows it’s important, nobody wants to deal with it, and most organisations do the bare minimum.

Then someone leaves the company. And suddenly that undocumented process they ran single-handedly becomes everyone’s emergency.

We’ve all been there. Let’s talk about what good documentation actually looks like, so you can stop pretending your Confluence instance is fine when it’s actually a haunted house of outdated wiki pages.

Why most documentation fails

The typical documentation cycle goes like this:

1. Someone decides “we need to document everything”
2. The team spends two weeks writing comprehensive docs
3. The docs are never updated
4. Six months later, the docs are more misleading than having no docs at all
5. Someone decides “we need to rewrite our documentation”
6. Repeat

The problem isn’t motivation. It’s sustainability. If your documentation process requires a dedicated effort to maintain, it won’t get maintained. People have actual work to do.

The four types of documentation you actually need

Divio’s documentation framework breaks docs into four categories, and it’s the most useful mental model we’ve found:

Tutorials — Learning-oriented. “Follow these steps and you’ll have a working setup.” New employee onboarding, new tool adoption, first-time process execution. These should be tested by someone who’s never done the thing before. If they can’t follow it without asking questions, it’s not finished.

How-to guides — Problem-oriented. “Here’s how to do X.” Assume the reader already knows the basics and just needs the specific steps for a specific task. “How to process a refund,” “How to deploy to production,” “How to set up a new client account.”

Reference — Information-oriented. “Here are the facts.” API documentation, configuration options, data dictionaries. Dry, comprehensive, and accurate. This is the stuff people search for when they need a specific detail.

Explanation — Understanding-oriented. “Here’s why we do it this way.” Architecture decisions, business rationale, design principles. This is the context that turns a process follower into someone who can make good judgment calls.

Most organisations only write reference docs (if they write anything at all). That’s like having a dictionary but no grammar book. You can look up words, but you can’t construct a sentence.

What good looks like in practice

Good documentation shares a few traits regardless of the format:

It’s findable. If people can’t find the docs, they don’t exist. This means a sensible folder structure, consistent naming, and ideally a search function that actually works. Notion and Confluence both offer decent search. Google Docs does not.

It has an owner. Every document should have one person responsible for keeping it current. Not a team — a person. Shared responsibility means no responsibility. Put their name at the top of the doc.

It includes a “last verified” date. Not just “last updated.” A document can be unchanged for a year and still be accurate if someone checked it recently. The date tells readers whether to trust the content or verify it themselves.

It’s scannable. Headers, bullet points, numbered steps, and bold text. Nobody reads documentation like a novel. People scan for the relevant section and read that. Write accordingly.

It’s honest about what it doesn’t cover. “This guide covers X but not Y. For Y, see [link].” Readers waste enormous time reading entire documents only to discover at the end that it doesn’t answer their question.

The maintenance problem

Documentation rot is the silent killer. Here are three approaches that actually work:

Embed docs in the workflow. Instead of a separate documentation portal, put the instructions where the work happens. Comments in code. Notes in project management tools. Steps in the actual form or system being used. If the doc lives alongside the work, it’s more likely to get updated when the work changes.

Schedule quarterly reviews. Set a calendar reminder. Every three months, document owners spend 30 minutes reviewing their docs. Delete what’s obsolete. Update what’s changed. Flag what needs a rewrite. Thirty minutes per quarter is far less painful than a week-long documentation sprint once a year.

Make it part of the definition of “done.” If a process changes, the documentation changes. If a new feature ships, the docs ship with it. This is easy to say and hard to enforce, but the teams that do it consistently are the ones with documentation that people actually trust.

Tools don’t matter (much)

People love arguing about documentation tools. Confluence versus Notion versus GitBook versus Google Docs. It genuinely doesn’t matter much. The best documentation tool is the one your team will actually use.

That said, a few things do matter:

• Version history — You need to see what changed and when
• Permissions — Not everything should be visible to everyone
• Search — If you’ve got more than 50 documents, you need search
• Link stability — URLs that break when pages are moved are a documentation killer

Beyond that, pick something and stick with it. Switching documentation platforms is almost never worth the effort.

Start with what hurts

Don’t try to document everything. Start with the processes that cause the most confusion, the questions that get asked most often, and the tasks that only one person knows how to do.

Interview that person. Write it down. Have someone else follow the instructions. Fix what doesn’t work. Publish it.

That’s it. That’s the whole process. Do it once a week and within a few months you’ll have documentation that actually helps people do their jobs.

The bar for good documentation isn’t perfection. It’s “better than nothing, and not actively misleading.” Start there. You’d be surprised how few organisations clear even that bar.