The Great Docs Restructuring

The Wrong Enclosure

In the last post I described how my forgetful partner needs a home suited to its nature: findable rules, compact knowledge, an entry point that works even without any backstory. My docs had been in the repo from the start — sensibly so, since that way they emerge together with the code and are versioned with it. And yet they were built for the wrong readership: for humans.

I’d set them up the way I still knew it from my thesis. One big, hierarchical functional spec — 2,500 lines of the finest concepts — and next to it the same thing again as a technical concept. Both neatly numbered:

# 1. Foundation
## 1.1 Setting
## 1.2 Manifesto
...

For a human that’s perfectly fine. You read yourself in once and, next time, flip straight to “1.2”.

Two Mistakes That Only Hurt with an Agent

Two decisions that hadn’t bothered anyone for years suddenly got expensive with an AI partner.

The numbering. At first this isn’t an agent-specific problem at all, but a general one: rigid chapter numbering with cross-references to those exact numbers makes it a pain to extend a document — every insertion shifts the numbers, every reference has to be dragged along. As a tidy developer, though, you rarely touch your docs after writing them anyway, so it never showed. With an agent that constantly writes and rebuilds documentation, the trifle becomes a permanent nuisance.

The size. A few large documents that describe the same context — spread across many chapters — over and over from different angles make it needlessly hard for the agent. He doesn’t flip, he loads — and has only two bad options: load everything (context 90% full of ballast) or cobble together a few greps and hope to catch the right thing.

The Fix: Docs Like a Wiki — but in the Repo

The fix was simple: split it up by domain, small files, chapter numbers out. References since then point to anchor links that travel with their heading, instead of to numbers that break with every reordering. The result is that the docs today read like a wiki — many small, clearly named pages instead of two monoliths.

I briefly considered just going with a real wiki then. But documentation belongs in the repo, for two reasons: first, that way it emerges together with the code and is versioned with it — the state of the docs always matches the state of the code. Second, in the file system an agent has far stronger and faster search tools than in a wiki: grep, glob, reading a file — millisecond-fast, without the detour through an API.

Here’s what it looks like today:

doc/
  audience/          # audience calculation
    fachkonzept.md   #   functional
    backend.md       #   technical, backend
    frontend.md      #   technical, frontend
  supply/            # film distributor & ad agency
  profile/           # profile and fatigue
  channel/           # channel economy
  ...
  fk/                # global functional spec
  tk/                # global technical concept
  crosscutting/      # workflow guides

Each feature a folder, inside it one functional file and one each for backend and frontend. And lots of linking: docs point to docs, docs to code — and the code back to the docs, via a package-info.java per domain. No matter which side my partner enters a feature from, he finds the other half.

A Trade-off: German Docs, English Code

There’s one bit of friction left that I deliberately accept. I think in German, the whole functional spec is German, and I have the domain terms in German in my head too — so the docs should stay German. On the other hand, it makes my eyes bleed when German terms are scattered all over the English source code.

The bridge is a single file: namensmapping.md. For each German domain term it fixes exactly one English code naming — “Werbevertrag” → advertisingContract, “Sendeplatz” → BroadcastSlot. New translations don’t come up ad hoc while generating code, but here first. That way the docs stay German, the code English, and nobody invents three names for the same thing.

Did It Help?

The whole docs rebuild wasn’t a gradual process but a big one-off push, in which I really only changed docs and no functionality. That let me measure the result by having the agent solve the same task once before and once right after the rebuild.

The method, in short:

Same prompts, both states. Each task ran five times per state, in interleaved order — so that neither state benefits from a warm cache.
Fresh head per run. Each run was its own memoryless session (headless claude -p), with read-only tools and no subagents. What’s measured is repo navigation, not day-to-day variance.
Measured: duration, token consumption (counted cache-neutrally), and work steps.
Quality graded blind. A second, independent agent graded the answers against the actual doc facts — it saw only the text, not which state it came from.

And here’s what came out (each after versus before):

Category	Task	Tokens	Quality	Effect
Trivial (grep)	“Which class computes the rating?”	± 0	same	no effect
Focused	“How does the film distributor work?”	+16%	errors 4/5 → 0/5	more accurate
Focused	“How does the audience calculation work?”	−29%	same	faster (−49% time)
Focused	“Switch profile to a target group?”	−44%	same	half as many steps
Global	“Redesign the frontend app”	−7 to −16% (variable)	same	slightly faster (~1 step, −28% time)

The pattern is astonishingly clear. On the trivial task the rebuild does nothing — the agent solves that by code grep, the docs aren’t on the path at all. On the focused domain questions the gain is large: sometimes half the time and a third fewer tokens at the same quality, sometimes the error rate from four out of five answers down to zero. And on the global-galactic task (“go design the whole frontend”) a small but shaky advantage remains: the duration drops noticeably and the agent needs about one work step fewer, but the token savings swing widely from run to run. Here it has to read in almost everything anyway — so finding individual parts faster helps little.

Not Just for the Agent

The restructuring wasn’t a compromise in the agent’s favor. I find the docs better myself today too: easier to extend, easier to find again, and less dependent on knowing their original order.

Documentation can be good in different ways. It can be a big, carefully built book — or a web of small, clearly connected pages. For humans both forms work. But the agent benefits markedly when it doesn’t first have to read the whole book to find the right chapter.

Humans read documentation top to bottom. Agents find their own way through. Good documentation allows for both.