The Documentation Was Never the Problem

Part two of three in a series that starts with AI Native Is Not a Tool Decision. Part one was DevOps 3.0.

The Fantasy We Gave Up On

Some time in the 2000s, software companies got properly excited about writing things down. We had computers now. We could have an employee handbook, and a handbook for this, and a handbook for that. Later we had wikis, then Confluence, then Notion. There was real energy behind it, and the energy was justified, because the prize was obvious: reduce friction, streamline how things get done, deploy best practice everywhere at once instead of teaching it person by person.

Then we found out it was bitter work.

People did not want to read handbooks. People did not follow the guidelines. People forgot. People skipped the fence. People went their own way even when their own way was worse for them and worse for the company.

Not because they were stupid, or lazy in any moral sense, or badly managed. Because a human brain is not a machine. It has a working set, it has a mood, it has a Tuesday afternoon. The long-standing dream was to write down everything about how we wanted to operate, and we found out it was impossible to cash in.

Plenty of companies still hold something written, produced in hope that someone would read it. It goes stale, it goes unmaintained, and it definitely goes unread. If you have a wiki, you know the exact page I am describing. It was written by someone who has since left, it describes a process that changed twice, and nobody has the heart to delete it.

The Reader Was the Bug

For most of my career I drew the obvious conclusion from all of that: documentation has bad returns. Write the minimum, keep it close to the code, accept that culture travels by apprenticeship and not by text.

I want to be careful here, because there is a cheap version of this essay in which I now say I was wrong about that. I was not wrong. That conclusion was correct, and it stayed correct for twenty years.

What was wrong was never the diagnosis. Documentation did not have bad returns because the writing was bad. It had excellent returns that were destroyed at the last step, by handing them to a lossy execution layer. Most of the value evaporated in delivery, every single time, and because the loss always happened in the same place we mistook it for a property of the documents.

So the failure was located in the reader. That was true then and it is still true now, about human readers, and anyone who has tried to roll out a handbook this year can confirm it.

What changed is not the analysis. What changed is that a second kind of reader turned up.

Agents read the thing. Then they do what it says. That is not a virtue, it is a mechanism, it is how they are built. Which means the constraint that made documentation a bad investment for my entire career has been lifted, not refuted. Same writing, same organisational effort, completely different return.

The documentation was never the failure. The reader was. We did not get the analysis wrong. We got a new reader.

That distinction matters more than it sounds, because it tells you what to do. If the old conclusion had been an error, the lesson would be to go back and write all the things we should have written. It was not an error. The lesson is that a door that was closed is now open, and it is open right now, and the work behind it has a payoff it has never had before.

Two Forces Pointing the Same Way

Something else happened at the same time, and it is the part I find genuinely lucky.

Every best-practice initiative I have ever run had to be pushed. You write the thing, you announce the thing, you remind people about the thing, and adoption is the entire battle from start to finish. This one pulls instead, and it is worth understanding why, because the usual explanation is too shallow to be useful.

The shallow version is that people are lazy. It is not that, and saying it that way gets you nowhere, because it frames as a character flaw something that is closer to a physical law.

Everything in nature moves down an energy gradient. Water finds the low ground, heat spreads out, and any system given a choice between two paths to the same place takes the cheaper one. We are not exempt from this. It is not a defect in us, it is the mechanism we run on, and it is the reason habits exist at all: a habit is the lowest-energy route to a result you have already decided you want. Most of what looks like discipline in a well-run company is just a set of gradients that happen to point somewhere useful.

Which is exactly why the handbook failed. Reading the handbook, remembering the handbook, and then choosing the documented path over the familiar one is a steeper climb than just doing it the way you did it last time. Every individual instance of skipping it was locally rational. The aggregate was a company that did not follow its own rules.

And it is why AI adoption pulls rather than pushes. Once someone has actually tried it, the agent becomes the cheaper path, and then no persuasion is required at all. There can be real scepticism up front, and there usually is. But it survives about one useful result. After that the gradient is doing the work and people ask for more access rather than having to be sold it. I have never once had to argue with a colleague about whether to use their seat.

And the agents, on the other side, want to read the documentation and follow it.

So the two things point the same way: humans who now find the documented path cheaper than the improvised one, and a reader that does what the documentation says. On top of that, the instructions are the only thing standing between a capable model and bland, generic output. I have not had a base like that before for getting best practice actually followed, and I do not expect to get one again.

It Is Not a Retrieval Problem

Here is the thing most people get wrong when they start. They assume the knowledge exists somewhere and the job is to plumb it in. Connect the wiki, index the Drive, point the agent at Slack.

It mostly does not exist. It lives in people's heads and in three-year-old Slack threads. So it is not a retrieval problem. The artifact has not been written yet, and no amount of connector configuration creates it.

Which means the real work is organisational, not technical. You are forcing an organisation to make its implicit knowledge explicit, which is slow and political and touches everyone's sense of what they are for. There is no vendor for that.

There is a specific version of this I have come to care about a lot. Much of a founder's effectiveness in a fifteen-year-old business is not talent and not risk appetite. It is an enormous passive build-up of context that never got written down. Everyone who joins later plays the same game with less of the board visible, and we call the difference seniority.

The reason to fix it now is the interesting bit.

The bottleneck was never capturing that knowledge. It was the human's ability to absorb it. You could hand someone a perfect fifteen-year briefing and their head could not hold it, so there was no point writing it. An agent can hold all of it, retrieve the relevant slice on demand, and never forget.

I made a narrower version of this argument in Still True: when AI fails on a task it is almost never because the model was not smart enough, it is because we did not give it the context. Intelligence stopped being our bottleneck more than a year ago. I could see that coming before the vendors had integrations, and it is the reason we started early.

Why We Put It in Version Control

I am a software developer. When I asked myself where to put company knowledge so that it would not rot, the answer was not a hard one.

We put it in the same system our engineers use to manage source code: git, which tracks every change ever made to a body of text, who made it, when, and why, and requires changes to be proposed and reviewed before they take effect. We called the result Atlas. It holds the company manual: what we sell, how we price, how we work, how we speak to customers, what our numbers mean. It publishes as a perfectly normal handbook website that, honestly, most people never visit, because they meet it through their agent instead.

If you are not technical, the instinct here is that this sounds needlessly complicated compared to a wiki. It buys four things a wiki cannot, and each of them is the answer to a way that wikis die.

• Review. A change to how we price something arrives as a proposal, with an author, a precise before-and-after, and somebody who has to agree to it. The knowledge base inherits an editorial process it never had.
• History. You can ask when a rule changed, who changed it and why, and get an answer rather than a guess or an argument.
• Visible staleness. This is the one I underrated. In a wiki, staleness is a vibe. Here it is a date, attached to every individual paragraph. You can automate against it.
• Vendor independence. The formats keep changing. What the industry called a "skill" when we started has already been joined by several other ways of feeding context to an agent, and the names will change again. If the underlying information is well structured and well maintained, you can publish it into whatever shape this year's tools expect.

That last point is worth dwelling on if you are choosing where to put this. Every AI vendor will happily host your company knowledge for you. They take it as an opaque upload, they lose the history of who changed what and why, and they leave you maintaining a separate copy per vendor by hand. Nobody would run their source code that way, and this is more important than most source code.

What Is Actually In It

Thirty-six documents at the time of writing. The industry calls each one a skill: a short piece of writing aimed at an agent, which it picks up and follows when the situation calls for it. Think of it as a briefing note that is guaranteed to be read.

They come in four shapes, and the shapes matter more than they sound like they should.

Underneath that there are five design rules that I would give to anyone starting this, because we learned all five the expensive way.

1. The unit of a file is the unit of reasoning, not the unit of topic.
2. Every fact has exactly one home.
3. Compose through dependencies, not copying.
4. "Relevant everywhere" means centralise harder, not duplicate more.
5. Load on demand, not always-on.

Any knowledge system has two failure modes: duplication and drift. Both have the same root cause, which is information existing in more than one home, which is why rule two is the one that actually matters. Break it once and you will spend a year discovering which copy people believed.

And there is a single test for whether something belongs in there at all: does it let an agent, or a colleague, make a call they otherwise could not? Foundational does not mean vague. The trap is a nice mission-statement document that changes no decision. Write things that change a decision. A pleasant summary that changes nothing is not worth the maintenance it will demand.

It Is Not an Engineering Project

If you take one thing from this post, take this. Atlas is not an engineering artifact and it would be worthless if it were.

Sales owns the largest share of the department-specific ones. Engineering owns the fewest. There are documents for marketing, for people operations, for finance, for how we speak to customers, for how our products should look and behave, for handling personal data, for customer service. Every one has a named owner accountable for deciding when it has gone out of date, and most of those owners have never written a line of code.

Design is the example I find clearest.

When a company decides it needs more design consistency, the instinct is to ask the designer for more screens. That is the wrong ask now. What you want is their taste and their user-experience judgment encoded once, in a design system that centralises the decisions and propagates them out to whoever writes the code, or the agents that do. The output of a design function stops being artifacts and becomes a system that produces artifacts correctly by default.

A lesson came attached to that, and it is not about design at all. When one part of the company had not picked any of it up, my instinct was to mandate: decide centrally, roll it out. A colleague pushed back with the obvious question I had walked straight past. Why not just ask them? Say this exists, we are building it, do you want in. They already know they need it. And if they say yes, you have the mandate with you instead of holding it over them.

He was right and I was wrong, and it took about ten seconds to establish.

The Inversion

This is the part I did not expect, and it is the strongest thing in this post.

For about thirty years, the central quality ritual in software has been code review: before any change reaches the product, another engineer reads it line by line and signs it off. It is the profession's main defence against mistakes, and it is where a great deal of senior time goes.

We have largely stopped doing it. I made that case in Everyone Produces Code Now, and the logic is simple: what the customer gets is the behaviour of the software, not its innards. If it does the job and the automated checks around it are honest, the implementation is not where the interesting judgment lives. We put that effort into automated checks instead, which never get tired and never approve something at five o'clock on a Friday.

Meanwhile, changes to the company manual we argue about.

Genuinely argue. We debate them, we push back, we send them back for another go. Because a document like that is not an implementation detail. It is a policy decision: a thing we settle together, as a company, about how we operate and what we think good looks like. Here, the textis the product.

So it needs human eyes. It is the one place where review is not optional.

Code review is dying, because the thing that matters is behaviour. Knowledge review is being born, because a written rule is a policy decision.

That reversal is the single most useful thing I can hand anyone thinking about this. We did not lose the discipline of review. We moved it up a layer, to where the decisions actually are, and the layer it moved to is one that most companies do not review at all.

What Stops It Rotting

Every time I present this, somebody asks the right question. Notion rotted because nobody had a reason to go back. If marketing writes a skill and the process changes, what makes them return and fix it?

Four answers, in descending order of how much I trust them.

Use is maintenance. The person who notices a skill is wrong is the person using it, and they notice at the exact moment they are diverging from it. They are sitting with an agent, doing the thing, and the thing goes sideways. That is the cheapest possible moment to catch it, and it happens for free because the skill is in the loop rather than in a folder.

A named owner. Every document has one. Their job is not to write it, it is to decide when it is out of date. We make owner sign-off a human obligation rather than something the system blocks on, which is deliberate: I would rather people understood the responsibility than learned to route around a robot.

Enforcement by machine, not by nagging. Change a document and you must record what changed and why, or the change is refused automatically. Anything that claims to depend on another document but never actually uses it gets flagged. And we insist that the document says what is true today while the change log says what changed, because mixing those two is the most common way these things rot: a page slowly accumulates its own history inline until nobody can tell which parts still apply.

An automated reviewer. Every proposed change is read by an agent working from a short document about what good looks like. We split it in two, because the person checking whether a pricing rule is factually correct is not the person checking whether the thing is filed in the right place.

And now the honest part, because the good version of this is not built.

Three things would make Atlas curate itself, and all three are written down as intentions rather than features. Freshness as a first-class field, because an eighteen-month-old note and a current source of truth look identical to an agent unless something says otherwise. Duplication detection at the door, semantically checking a new skill against everything Atlas already holds so it can say "this definition already lives in the glossary, reference it instead", which is cheapest at the moment of writing and almost impossible later. Drift detection over time: if a skill's dependency changed more recently than the skill did, flag it for review.

The symmetry is the point. The same capability Atlas exists to give agents and people, turned inward to maintain its own integrity. We have not done it yet. I am telling you because a post that only lists the parts that work is not worth reading.

Continuous Delivery for Context

We learned something with software that took years and some scar tissue: you do not deploy on Fridays, you deploy all the time. Big infrequent releases are where risk accumulates. Small constant ones are where it dissolves.

That applies to knowledge deployment too, and almost nobody treats it that way.

In Atlas there is no publish step at all. The moment a change is approved, it is live everywhere: in the tools our people use, in the handbook website, in the hands of every agent that might need it. Approving the change is the deployment. One source produces every one of those destinations, so they cannot disagree with each other. A scheduled job even refreshes our org chart from the HR system every morning and proposes the update itself.

Getting there involved some work I am fond of and glad to have thrown away. Before the AI vendors offered any way to plug a body of company knowledge into their products, I built the distribution myself with scripts and an automated browser that logged in and pasted things into each vendor's console overnight. It was held together with tape. It also worked, and when the vendors did ship the real thing some months later, we had already been operating that way long enough to know what we wanted from it, and simply deleted our version.

I would rather be the person who built the ugly thing early than the person who waited for the standard.

Keeping the Jargon at Arm's Length

Now the obvious objection, and it is a fair one. Everything I have just described is the machinery software engineers use, and most of the people who should be contributing to a company manual are not software engineers. Version control is a lot to put in front of somebody who works in finance.

So we wrote an operating manual for the whole thing, and then we aimed it at the agent instead of at the person. It tells the agent how to behave when the author is not a developer. Two of its rules I would steal if I were you:

A finance colleague describes the change they want in ordinary words. The agent does the rest and comes back with a proposal for their owner to approve. They never see a branch and never need to know what one is. It is not flawless, and it shows in places, but the technical furniture is somebody else's problem by design.

One more small thing that cost us to learn, in case you go down this road. Every document ends with a line stating that it is maintained centrally, and that edits made anywhere else will be overwritten. We enforce that line automatically. The reason is that in every chat window and vendor console these documents look editable. There is a text field. You type in it, you feel productive, and your change is silently destroyed the next time anyone updates the real copy. Cheap line of text. Expensive lesson.

Does Governance Become the Bottleneck?

The sharpest follow-up I get is this: if a skill is a policy decision and policy decisions need human review, then you have put human review capacity directly in the path of everything your agents do. Does governance not become the new constraint?

Probably, eventually. It has not bitten us at sixty-one people, and I think there is quite a long way to go before it does. I am not going to manufacture a caveat I have not actually experienced. When it bites, I will write that post.

Where This Leaves You

If you are wondering where to start, do not start with a platform decision or a vendor decision. Start by picking one thing your company knows that currently lives in one person's head, and write it down in a form that changes a decision. Put it somewhere with review and history. Then use it, and fix it the first time it is wrong.

That is the whole method, and it is the same method as the platform post: take the decisions, consolidate the knowledge, put it somewhere agents can read it. The technology is not the hard part. The hard part is that your company has to decide what it actually believes, in writing, where people can disagree with it.

Which is uncomfortable, and useful, and would have been worth doing even if the agents never showed up.

Next: what we did with it, the four tests an agent has to pass before it gets a job, and the honest version of what all this did to people's roles.