Skip to content
All writing ‹ Part 04 of 08 · Docs in the AI Era: Keep It Simple
Engineering · 5 min read

Strict Rules Only Where a Machine Checks

Map your docs to the four Diátaxis types. Keep current state apart from history. Make a rule strict only when a tool checks it. The rest are habits.

We already have doc types. We just never called them that.

Diátaxis sorts every doc with two questions. Does the reader want to do something, or to understand it? Are they new to it, or using it at work? Here is how our own files answer them.

Q1 Does the reader want to dosomething, or to understand it? do Q2 New to it,or at work? understand Q2 New to it,or at work? new to itTutorialREADME Quick Start at workHow-to guideRUNBOOK new to itExplanationARCHITECTURE · PRD at workReferenceAPI docs
Run a file through the two questions, and you know which type it is.

Map our files onto those four types, and the picture is clear.

Our fileDiátaxis typeLives inReader
README Quick Starttutorial: learn by doingrepoengineer, AI agent
RUNBOOKhow-to: do one taskrepoengineer, AI agent
ARCHITECTUREexplanation: why it works this wayrepoengineer, AI agent
ADRdecision recordrepoengineer, AI agent
API docs (built from code)reference: look up factsrepoeveryone
PRD / overviewexplanationteam wikiPM and business roles, new team members

Keep current state and history in different files

  • Current-state docs: README, ARCHITECTURE. Keep only the latest version and edit it in place. It must be true today.
  • History docs: ADR, journal. Only add new entries. A new entry replaces an old one, and you never edit the old one.

This matches two kinds of memory: “what is true now” and “what happened when”.

Two kinds of rules: a machine blocks one, people remind the other

A machine can check the first kind. CI runs on every push, and if a doc breaks the rule, the build fails. Nobody can forget it. Examples: required fields exist (owner, date), links are not broken, the file is in the right folder, and the Markdown format is valid.

Only a person can see the second kind. A tool cannot judge how much detail is enough, or whether a doc fits its reader. For these, the team agrees, and reviewers remind each other in code review. Examples: how much detail to write, who to write for, clear and plain wording, and the ADR template (Status, Date, Author, then Context → Decision → Consequences).

Habit: the team agrees→ reviewers remindhow much detail · which readerplain wording · ADR template add a toole.g. a commit message check Strict: a tool checks it→ if it fails, the build failsrequired fields · linksright folder · Markdown format
A habit becomes a rule only when a tool can check it.

If nobody can check a rule, nobody follows it. Then people stop trusting every rule. So keep the strict side short.

A habit can move to the strict side when you add a tool. The commit format <type>: <title> (TICKET-123) is one example. Add a commit message check, and the habit becomes a rule. To see where that check runs, read Keep Docs Alive: Three Reminders, One Direction.

Lower the load on the reader

Habits that every senior engineer already knows stay out of our docs. Link to a standard once, for example Conventional Commits or the ADR template. Do not rewrite it. New team members and AI agents follow the link.

Without fields like owner and date, nobody can tell that a doc is old. The team chooses which fields every doc must have: owner, last checked date, status, reader, ticket number (Jira, Linear), tags, end date.

A rule that a machine checks is a rule. Everything else is an agreement.

References

Related: see how names carry meaning, see where the checks run, or go back to the series overview: Docs in the AI Era.

Tags #docs-in-ai-era #documentation #llm
↑↓ navigate ↵ open esc close