How to write reference docs that don't rot

I keep landing on the same architectural shape when I write reference docs that have to hold up across multiple projects.

Two layers. A universal layer underneath. A per-instance layer on top.

The universal layer holds the constants. The things that are true no matter which project, brand, voice, persona, skill, or instance you’re applying the doc to. The per-instance layer holds the variables. The things that change based on context, surface, audience, register, or scope.

I didn’t set out to discover this pattern. It surfaced from a voice doc I was rewriting earlier this month, and once I named the shape, I started seeing it in five other places I’d already built. The places where a doc was holding up well over time were the places where I’d accidentally separated stable from variable. The places where a doc was decaying with every new instance I tried to fit under it were the places where I’d mashed both layers together and called it one thing.

This essay is what that pattern looks like when you name it deliberately.

i.The rot pattern in single-layer docs

Here’s how a single-layer reference doc decays.

You write a voice guide. The first version is for one project, so the doc reads as a single coherent block. Rhythm rules and word-choice tendencies and genre conventions all sit next to each other on the page. It works.

Then you add a second project under the same voice. The second project shares some of the rules, breaks others. You patch the doc. Add a paragraph that says except when working on Project B, in which case the rule inverts. The doc still works, mostly, but a reader has to mentally track which rules are universal and which are project-specific.

Then a third project shows up. You patch again. Now the doc has three layers of exceptions woven through every section. The universal rules are buried inside the project-specific rules. The next time you sit down with the doc, you can’t tell what’s load-bearing from what’s incidental.

The doc has rotted. Not because any rule was wrong. Because the structure couldn’t accommodate growth without conflating two kinds of statement.

ii.The two-layer shape

The fix is to separate stable from variable before you write anything that lives under the doc.

Universal layer first. What is true regardless of which instance applies the doc? Those statements get their own section, and they get written as if no instance has been chosen yet. They hold as principles, constants, craft rules, structural commitments. They earn their place by surviving every instance you can think of.

Per-instance layer second. What changes based on which instance applies the doc? Those statements get their own section, organized by instance, written as overlays on top of the universal layer. A reader walking the doc reads the universals first, then layers the relevant instance column on top. Two passes. Two distinct purposes. Two structurally separate parts of the same doc.

The shape isn’t novel. Anyone who’s written CSS has done a version of it. Anyone who’s designed an inheritance hierarchy has done a version of it. What’s worth naming is that the shape applies far past code, and that getting the two layers wrong is the most common cause of doc rot I see in my own work.

iii.Where this applies

Five places I’ve used the two-layer pattern in the last month, all of which were rescues from a single-layer doc that had started to decay.

A prose-voice doc with a section for universal craft constants (rhythm, restraint, what voice protects across genres) and per-project surface columns (one column per universe being written in, each holding the genre-specific overlays that sit on top of the universal craft). The universal craft is what makes the prose recognizable as one author’s. The per-project surface is what makes it land inside its genre.

A brand-voice doc with the same shape. Universal voice principles that hold across every platform. Per-surface registers that translate those principles into the conventions of LinkedIn versus blog versus X versus YouTube.

A personality doc for an AI agent, with universal disposition (the traits that hold regardless of what task is in front of the agent) separated from per-mode register (how the agent’s voice shifts when working on creative content versus technical specs versus brand drafts).

A skill-design template, with universal skill-mechanics (what makes any skill testable, composable, idempotent) separated from per-skill specifications (what this particular skill does, triggers on, returns).

A reference doc for tool-vetting, with universal gates that apply to any third-party code (provenance, install-time exec, runtime surface, dependencies, reproducibility) separated from per-class overlays (what those gates look like for an MCP server versus a CLI versus a plugin).

In every case, the doc held up better once I split the layers than it had when I tried to write one combined doc. The universal layer became reusable. The per-instance layer became extensible without touching the universal layer. Adding a new instance meant adding one new column or section, not rewriting the whole doc.

iv.How to know which layer a statement goes in

The test is straightforward once you’ve named the pattern.

Take a candidate statement. Ask whether it would still be true if the instance changed. If yes, it belongs in the universal layer. If no, it belongs in the per-instance layer.

The hard part is being honest about which statements actually pass the test. The first time I split a voice doc into two layers, I sorted half a dozen rules into the universal layer that should have been per-instance. They felt universal because the project I’d written them for was the only project I’d been working on. Once I tried a second project under the same doc, the rules broke. The split was wrong.

The lesson there is that universals have to be tested against multiple instances before you trust them. If you’ve only ever applied a rule to one project, you don’t yet know whether the rule is universal or just project-specific in disguise. A statement isn’t a universal until it has survived contact with at least two different instances and held up unchanged.

This also means the universal layer should be small. Most rules turn out to be per-instance once you stress-test them. The universals that survive are the load-bearing ones, the deep craft constants, the structural commitments that aren’t really negotiable. That’s what makes them universal in the first place.

v.What this earns

The thing the two-layer pattern earns is doc longevity.

A single-layer doc rots as you add instances. Every new instance forces a patch, and every patch makes the doc harder to read. Eventually the doc is more exception than rule, and you either rewrite from scratch or stop trusting it.

A two-layer doc grows without rotting. Adding a new instance means writing a new column or section in the per-instance layer. The universal layer doesn’t move. Readers who know the universals from a previous instance don’t have to relearn them. They just read the new column.

There’s also a clarity gain that compounds over time. Once the universal layer is locked, you can refer to it across other docs. Other reference material can cite the universals without having to restate them. The universals become the spine that multiple downstream docs hang off of. Per-instance specifics stay scoped to their own surfaces.

I think this is the shape most well-aging reference docs converge to whether their authors named it or not. The good ones separate what’s stable from what varies. The decaying ones don’t.

If you’ve got a reference doc that feels like it’s getting harder to update every time you touch it, the diagnostic is probably this. Walk the doc and ask which sentences would change if the instance changed. If most of them would, the doc is single-layer and it’s time to split.

The universals will be smaller than you think. The per-instance overlays will be larger. That’s the right ratio. That’s the shape that holds up.

Drafted with Bishop, my AI partner.
Words picked, edited, and approved by me.