The story
There are two ways a documentation system can fail you.
The first is that the AI simply doesn’t know what it’s working with. So instead of getting on with the job, it starts exploring — poking around, reading things it should already know, trying to piece together a picture of the situation from scratch. You watch it feeling its way around in the dark, and you realise it has no idea where it is.
The second is more insidious. The documentation exists, the AI reads it — but the documentation is wrong.
When I moved my websites to a new server, I stopped using the software I had been using to manage it. The documentation still said I was using it. So when I asked for something to be done, the AI went looking for a setup that wasn’t there. It wasn’t exploring aimlessly. It was following the map. A map of somewhere that no longer existed.
I had written that map. I had just forgotten to update it.
Both problems have the same root cause: documentation written by a human at a particular moment, which stays fixed while everything else moves on. I looked at the number of files involved — the notes, the instructions, the records of how everything fitted together — and I knew I was not going to keep them current myself. That is not a realistic expectation of any person managing a complex system alongside everything else they have to do.
So I stopped thinking about documentation as something I write and maintain. And I started thinking about it as something the system maintains itself.
What I built — gradually, over many sessions — is this: every time the AI starts working on my server, it reads a short index file first. That file tells it exactly what to read and what not to read. It loads two documents: one with the rules for how it should behave, one with a map of the current setup — what’s where, what’s called what, how to restart things if they go wrong. That’s it. Nothing else, unless the specific task requires it.
The map is the key part. When the AI discovers something that isn’t in it, the instruction is: find it, then add it. The documentation updates itself through use.
The results have been concrete. Starting a session now takes a fraction of the time it used to. The AI arrives knowing what it’s working with. It doesn’t spend the first part of every session finding out.
The point
The instinct when documentation goes wrong is to write better documentation. Be more thorough. Keep it current. That instinct is reasonable, and in my experience it is not quite enough — because documentation maintained by hand degrades the moment your attention moves elsewhere. It is accurate on day one, quietly wrong by month six, and abandoned by month twelve.
The more useful question, I think, is structural: who is responsible for keeping the documentation accurate, and what happens when it goes out of date? If the answer is “me, manually, whenever I remember,” the answer is probably not good enough for anything that changes regularly.
What I have now is a system where the map stays current because the thing that uses it is also the thing that updates it. I did not arrive at that by trying harder to write better notes. I arrived at it by asking a different question.