Documentation That Stays True

The problem

Client systems are never finished. Automations change, fields get added, someone fixes a bug on a Friday. Six weeks later the README says a table is "blocked" while the table sits live in the base and its ticket reads resolved. That exact thing happened. It became a rule.

The way I work makes the problem sharper. I build with an AI collaborator, and an AI session knows exactly two things: what the documentation says, and what it can query live. When the session ends, everything learned in conversation is gone unless it landed in a file. In that setup documentation isn't a nice-to-have. It's the memory.

The goal isn't more documentation. It's documentation where every fact has exactly one home, so there's only one place for it to be wrong.

The six pieces

Every client workstream carries the same six pieces. Skip one when there's nothing to put in it. Don't invent a seventh.

Piece	Question it answers	Changes
README	What is this system, how does it behave, how do I reach it?	Rarely
Automations inventory	What machine implements it, exactly?	Every time the machine changes
Known issues	What's broken, fragile, or surprising right now?	As issues open and close
Feature specs	Why was this built this way?	Frozen at delivery
Tickets	What did the client ask, and what did we answer?	One per request
Scripts	The code, split by where it runs	With the machine

The README speaks functional, the inventory speaks technical

The test: if a sentence needs a trigger, a filter condition, or a field ID to be true, it doesn't belong in the README. If it describes what a person or a record experiences, it does.

One file for the whole machine

A button writes a field, the field feeds a view, the view triggers an automation, the automation runs a script. That chain is one thing. Splitting it across files guarantees the pieces drift apart.

Known issues live apart because they age differently

A system description is stable; issues open and close. Mixing the two is how stale state ends up inside permanent documents.

Specs freeze at delivery

What the system is lives in the README. What it became, and why, lives in the spec. Rewriting a spec to match the present destroys the record of why the past made sense. After delivery, the only edit is an addendum line.

Scripts split by one question

After this is finished, does the code still run? If yes, it's deployed code, a live dependency someone has to be able to find. If no, it's build code, a record of how the system got its shape. Different lifetimes, different readers, different folders.

The rules

One fact, one home. Files link; they never restate. If updating one fact means editing two files, the structure is broken, so fix the structure. The copy nobody updated becomes the lie somebody reads.

Touching the machine without updating the inventory is unfinished work. Same change, same session. An inventory with only a capture date is a photograph, and photographs of machines are stale the next day.

Every state assertion carries a date. "Blocked", "doesn't exist yet", "built and verified": always with a date, and a reader weeks later verifies before trusting.

Query what the API can return, document what it can't. Schema, formulas and record counts never get copied into the docs; store the query that returns them instead. Automations, view filters, interface elements and third-party integrations are invisible to the API, so they exist only if the docs record them, from evidence, with the date they were read.

Issues close by moving, never by rotting. Fixed: delete the entry. Accepted as permanent: it isn't an issue anymore, it's behavior, so the fact moves into the system description.

Access is pointers, never secrets. Every workstream says which credential to use, what it can and can't do, and where it lives. Never the value.

Write rules as tests with their reasons attached. A bare verdict invites a smarter reader, human or model, to "improve" it. A rule that carries its why lets that reader re-derive the same answer and stop.

The same idea, before the build: state the problem first

Documentation keeps the system true after it's built. The same discipline applies before a line of design exists: I write the problem list first, and stop until it's agreed.

One sentence per problem, with no solution language. If the sentence names a table, a field or a tool, it's a solution wearing a problem's clothes.

On one request, a client reported two symptoms: renaming a document folder broke its link, and renewals got duplicate folders. Underneath were three problems, and the one carrying the weight wasn't in the ticket at all: everything referred to folders by path. Solve that one first, and the other two shrink from a migration to an edit.

Then decide the reversible, and ask only the expensive. If rollback is cheap, pick one and say so: "we chose X, it changes in one edit if you want Y." Ask the client only for business definitions that are theirs to give, or for true gates like access.

What it buys

Any person or session files the same fact in the same place

Questions closed once stay closed

Specs keep rejected ideas from coming back during the build

Findings become reusable rules instead of tribal knowledge

That last one is concrete. A sync defect found on one project became four rules in a shared guideline the same week. The story is in One dashboard, seven sources.

Start small

The whole structure fits in one folder per workstream. Start with the README and the known issues file; add the rest the first time you need it.

client/workstream/
  README.md          what it is, how it behaves, how to reach it
  automations.md     the machine the API can't see
  known-issues.md    what's broken right now, dated
  feature-spec.md    why it was built this way, frozen at delivery
  tickets/           one file per client request
  scripts/
    deployed/        code the platform runs on its own
    build/           code that ran to shape the system, then stopped

One last thing

Documentation doesn't go stale because people are lazy. It goes stale because a fact lives in two places and only one of them gets updated.

Fix the structure, not the discipline.

Documentation that stays true

The problem

The six pieces

The rules

The same idea, before the build: state the problem first

What it buys

Start small

One last thing