What is really going on with almost up-to-date documentation" == bullshit?

An Absolute Thesis. And Why It’s Honest.

Documentation either exists, or it doesn’t. Full stop.
I know how that sounds. Too sharp, too absolute, too little nuance. Someone will write in the comments that context matters, that it depends on the project, that surely something is better than nothing.
It isn’t.
That’s the core of the problem.
“80% up-to-date” is not documentation. It’s a trap. And a much more dangerous trap than having none at all, because it operates silently. When documentation doesn’t exist, the team knows it has to ask, verify, explore. When documentation almost exists - the team trusts it. They read it, assume it’s true, and act on the basis of something that has been describing a different world for the past six months.
Think of a road map. If the map is blank - you know you have to explore. If the map is from 2019 and someone labeled it “80% up-to-date” - you drive down a highway that no longer exists. And you don’t know it doesn’t exist until you run into roadworks or a tree across the road.
Out-of-date documentation isn’t zero. It’s a minus. It wastes the time of everyone who consults it. It creates a false sense of security. And, worse still, it builds trust in something that doesn’t deserve that trust.
This isn’t purism. It’s pragmatism. Because time is expensive, and trust - even more so.

What Documentation Is NOT. Three Myths.

Myth 1: “The documentation is in the code.”
This is one of the favorite arguments I hear from good engineers. And I understand where it comes from - readable, well-written code really can say a lot. But code describes how. Documentation describes why, for whom, and what will happen when something goes wrong.
I once encountered a system where the “documentation” was a code comment: // TODO: describe this someday. Date of the comment: four years earlier. Nobody knew whether someone had described it somewhere else at some point, or whether there had simply never been time. So the team asked each other. Verbally. Like an oral tribal tradition. Knowledge circulated in people’s heads rather than in documents - which worked perfectly until half of those heads changed jobs.
Code as the only documentation is also an invitation for a specific audience: developers who know that language, that context, that system. The business won’t go digging through a repository. Operations won’t find an emergency procedure for a 3 a.m. outage in the code. An end user won’t read classes and interfaces to find out how to reset a password.
When did you last see a system whose code explains itself - to all audiences at once?

Myth 2: “We have documentation - there’s an architecture document from 2021.”
An architecture document is not system documentation. It’s wishful thinking frozen in a PDF.
Documentation describes the existing, running system - as it is today, not as it was meant to be three years ago. At one company where I did a review over several months, all the architectural documentation described a “to-be” version. The “as-is” system existed nowhere except in the heads of the people who worked on it. And those people left constantly. With every departure, the company lost a piece of knowledge about how what they had built actually worked. Nobody counted this. Nobody connected staff turnover to the rising cost of onboarding and production bugs.
Design documents and documentation are two completely different things. And conflating them is a recipe for chaos - more on that in a moment.

Myth 3: “We have documentation - it’s on Confluence.”
Confluence is a tool. Not a guarantee of quality, currency, or usefulness of what lives inside it.
At one company I found a page titled “Current System Architecture.” Date of last edit: three years earlier. Below it, six comments from developers - one wrote that this feature no longer works, another that they changed it in Q2, a third asked whether this referred to the previous version. None of them updated the page. Each added a comment and went back to work. And so, for three years, a document titled “current” described a system that had long since looked different.
Living documentation. Very much alive. Except it died a long time ago and nobody officially announced it.

Documentation vs. Design. These Are Not Synonyms.

Before we get to how to create documentation, I need to pause on one distinction that gets mixed up in practice all the time.
Documentation is a description of reality. It describes the system as it exists now - its architecture, behavior, integrations, constraints, procedures. When someone reads the documentation, they should be able to understand how the system works today, without asking anyone. Documentation is a consequence of what has been built. It is updated together with the system. If the system changes but the documentation doesn’t - the documentation stops being documentation and becomes a historical curiosity.
A design document (design doc, RFC, ADR) is a description of the expected target state. It describes what is to be built or why a particular decision was made. This is also a valuable artifact - especially ADRs, i.e. Architecture Decision Records, which document why a decision was made one way and not another. But a design document is not system documentation. It’s a record of a thought and decision-making process. A design document can be outdated, may describe things that ultimately were never built, may be an alpha version of something that looks completely different in production.
The problem begins when a design document becomes the only “documentation” - when nobody describes what was actually built, because “we have an architecture document.” That’s like handing a buyer the blueprints instead of the keys to the apartment and saying: “Well, it’s all described in here.”
The distinction is simple:
A design document answers the question: “What do we want to build and why?”
Documentation answers the question: “How does what we built actually work?”
Both are needed. But only one of them tells the truth about what happens in production at 3 a.m.

Three Simple Steps. Genuinely Simple.

Step 1: Start with people, not content
Before you write anything - ask who you’re writing it for.
This is not philosophy or management by objectives. This is a list of people you call or invite for 30 minutes. Developers on the team, developers from other teams, people from the business, operations, end users - each of these groups has a different frustration with documentation. Each different frustration is a clue about what good documentation for that group should contain.
Questions worth asking in each conversation: what do you need to know to avoid wasting time? What happens when you don’t know something? Where do you look for answers when the documentation doesn’t help?
The answers are usually different for each group. And that itself is information.

Step 2: Break documentation down into types
Different groups, different needs. Obvious. And yet the vast majority of companies produce one monster - one wiki, one Confluence, one “central place for all documentation” - that fits nobody, because it tries to serve everyone at once.
The output of a good step one is a list of several different documents, not one document for everyone. Developers on the same system need architecture docs, ADRs, and design decisions - ideally close to the code, in the same repository, so that a change in code and a change in documentation go together. Developers from other teams need API contracts, event descriptions, integration schemas - in a format they can consume automatically. The business needs descriptions of use cases, system behavior, and its constraints - in language that doesn’t require knowing the code. Operations needs runbooks and incident procedures - simple, unambiguous, written for a situation where something is falling apart at 3 a.m. and there’s no time for interpretation. End users need instructions, FAQs, tutorials - and in a place they can reach themselves without asking anyone.
Each of these documents has a different owner, a different update frequency, and a different format. It’s not one wiki. And that’s OK.

Step 3: Verify usability - this step almost nobody does
This is the most important step. And the most frequently skipped - because once the documentation is written, everyone is tired and wants to get back to real work.
But writing documentation is not the same as creating useful documentation.
When you have a finished document, go to someone from the target group and say: “Check whether this is useful for you. Do something real with it.” Sit next to them. Observe. Where do they stop? Where do they keep scrolling because they can’t find the answer? Where do they reach for the phone to ask someone instead of using the document?
This isn’t a code review. It’s user testing for documentation. And it works exactly the same way - without it, you’ll never know whether what you’ve written is understandable to anyone other than yourself. Because the author of documentation suffers from the curse of knowledge - they know too much to see what’s missing from the text.
Concrete questions to ask after the session: after reading this, do you know what to do? Is there anything here you don’t understand? Is anything missing that you were looking for? And finally - tell me in your own words what this system does.
If the answer to the last question differs from what you wrote - you have feedback. Useful, free, and concrete. And you’ve just saved someone two hours of searching for answers in a document that lies.

Who Needs What. Really.

An example of what a documentation maintenance strategy looks like for me:

Each row has a separate owner. A separate priority. A separate responsibility for currency.
If with every change in the system you don’t go through this table and ask “which documents need to be updated now?” - in a few months you’ll have documentation that can’t be trusted. And the clock is already ticking.
And if you’re working in Agile or Scrum - there’s one concrete move to make right now. Add to your Definition of Done the update of every required document for that change. Every one. With every completed increment. Because if you don’t update - better to delete. Really. A blank page is more honest than a page that tells lies.
…
Because documentation either exists. Or it doesn’t.
There is no such thing as “almost up-to-date” documentation. It’s like being “a little bit pregnant.” Either you are, or you aren’t. And it’s worth knowing which side of that line you’re on - ideally before someone from outside asks.

How much of your documentation can you trust today without checking?
And when did you last ask someone outside your own team whether it’s useful to them?