Death to the Template – LonestarDomains.com

Abolishing Documentation Theater Without Losing the Knowledge That Keeps a Business Alive

Someone left an organization today. The documentation they left behind is unreliable, or it does not exist.

The wiki page for their service still has last year’s architecture diagram. The required design document is twelve pages of “N/A,” a pasted screenshot, and a risk section copied from another ticket. The runbook says to bounce a box that was decommissioned in March. The people who remain will spend the next two weeks reconstructing intent from Slack threads, pull-request comments, and whatever the departing engineer happened to remember in an exit conversation that nobody recorded.

This is not a documentation shortage. It is a ritual that produces the appearance of knowledge while the actual knowledge walks out the door.

The goal is not in dispute. An organization needs an accurate, searchable account of how its systems work and why they work that way, so the business does not buckle when people leave. The failure is the method: we still force 21st-century software—dynamic, multi-repo, continuously deployed—through 18th-century paperwork. A human is handed a template and told to perform completeness. The rational response is malicious compliance.

The way out is not a better template. It is to decouple the goal of documentation from the labor of documentation, and to move that labor onto systems that already see the work.

What documentation theater actually is

Documentation theater is the production of documents so that a box can be checked, a gate can turn green, or a process can claim to have been followed. The artifact is the point. The reader is incidental.

It shows up as:

A design-doc template that must be filled before a pull request is allowed to merge, regardless of whether the change needs a design.
A Confluence space that is “complete” because every service has a page, even if half the pages describe a system that no longer exists.
Architecture Decision Records started with enthusiasm in January and abandoned by April, because writing the ADR became a second project.
Security questionnaires and compliance packets assembled from stale diagrams because the living system has no attested snapshot.
Onboarding guides that teach the org chart of two reorganizations ago.

Theater is not the same thing as documentation. Good documentation answers a real question at the moment someone has it: What happens if this endpoint dies? Why is this parameter set this way? Who owns the fallback? What did we try that failed? Theater answers a different question: Can we prove, in a review meeting, that a document exists?

Developers are not allergic to explaining systems. They are allergic to formatting explanations for an audience that will never read them. When the ritual is expensive and the artifact is unused, the organization trains people to optimize for the ritual.

The goal is resilience, not paper

Name the actual requirement without the costume:

A new owner can operate the system without a séance.
A reviewer can recover why a decision was made, not just what shipped.
An incident responder can find the current failure modes and the intended fallbacks.
The organization can show, at a point in time, what it believed to be true and who attested to it.
Search works. The knowledge is not trapped in a folder named Final_v7_USE_THIS.

Those are properties of a knowledge system. A template is one historically cheap way to fake those properties on paper. It is a poor way to maintain them in a codebase that changes every day.

If you accept the properties and reject the costume, the design problem becomes clear: capture structure from the system itself; elicit intent from humans only when the system cannot see it; keep a living, queryable synthesis; and give leadership something stronger than a checklist—coverage, freshness, and attestation.

Why the usual alternatives still collapse into theater

Killing Word templates is not enough. Most “modern” substitutes recreate the same human burden with nicer fonts.

Confluence and the corporate wiki optimize for creation, not truth. Pages are easy to start and expensive to keep honest. Ownership decays. Search returns seven versions of the same service. The wiki becomes a graveyard with good navigation.

Docs-as-code is a genuine improvement. Putting documentation in the repository, reviewing it in pull requests, and deploying it with the product attaches docs to the same change stream as code. It still fails when a human must author the prose. The pull request that changes a timeout does not automatically update the paragraph that explained the old timeout. Drift is merely version-controlled.

Architecture Decision Records are the right shape for intent: a short record of context, decision, and consequences. They fail as a process when they are another template a human must remember to open. Most “why” never becomes an ADR. It lives in a Friday afternoon comment: “we had to raise this because the vendor rate-limits bursts.” That sentence is the asset. The ADR template is the tax.

Generated API references and infrastructure diagrams solve the “what is it right now” problem for the slices they can see. They cannot explain a political constraint, a vendor incident, a regulatory interpretation, or the fallback nobody implemented because the risk was accepted in a meeting that produced no artifact.

Each of these tools is useful. None of them, used as a human writing assignment, solves departure. The missing move is to stop asking humans to produce the document, and start asking systems to produce the document from signals humans already emit—plus a few targeted questions at the moment of change.

Documentation is not one job

A single template pretends that one artifact can serve four different jobs. It cannot. Split them.

Job	Question it answers	Best source	Human role
System reference	What is this, right now?	Code, schemas, config, OpenAPI, infra-as-code, service catalogs	Almost none. Review exceptions.
Decision memory	Why is it this way?	Commit messages, PR discussion, tickets, and short elicited answers	Answer two questions when the change is semantically interesting.
Operational judgment	What do we do when it breaks?	Runbooks derived from alerts, dependencies, and stated fallbacks	Confirm fallbacks and missing paths.
Attested promise	What did we claim, to whom, as of when?	Signed snapshots, approvals, control mappings	Attest. This is leadership’s real need.

Theater happens when job four—the attested promise—is imposed on jobs one through three as a blank form. Engineers are forced to manufacture a static promise about a dynamic system, so they manufacture fiction.

The recommended system treats jobs one through three as derived products and treats job four as a thin, explicit attestation layer over those products. That is how you abolish the ritual without abolishing accountability.

The no-theater architecture

In a world where the theater is abolished, documentation is an automated byproduct of development. The human’s job is to supply raw context and intent. An agent builds, formats, links, and maintains the artifacts.

Three layers replace the corporate template. A fourth layer makes the result trustworthy enough for people who do not write code.

Layer 1 — Ambient context capture

Stop asking a developer to fill out a form that restates what the repository already knows.

An agent watches the development lifecycle with read access to the signals that already exist:

Code commits and pull-request diffs
Structural changes in configuration and infrastructure definitions
Evolving data schemas and API contracts
Ticket and requirement links
Service catalogs, ownership files, and on-call rotations
Alert definitions and dependency graphs
Prior intent records and existing ADRs

This is not surveillance of keystrokes. It is the same visibility a careful staff engineer already reconstructs by hand after someone leaves—except it runs continuously, while the change is still cheap to explain.

The output of this layer is not a document. It is a change graph: what moved, what depends on it, who touched it, which ticket claimed to justify it, and which existing explanations are now stale.

Ambient capture will be noisy. Most commits are not architecturally interesting. The system’s first product decision is ranking: ignore formatting-only diffs; escalate schema changes, timeout and retry changes, authz rule changes, data-retention changes, new egress, deleted fallbacks, and anything that alters a publicly visible contract.

Layer 2 — The two-question interview

Structure can be inferred. Intent usually cannot.

Instead of a ten-page gate before work starts, the system interrupts at the moment the interesting change is about to become permanent—on the pull request, or as a required check before a production deployment—and asks a small number of targeted questions generated from what it already observed.

Not a form. Two questions, maybe three, grounded in the diff.

Examples:

“You changed statement_timeout from 15s to 60s on the billing replica. Why this value, and what breaks if the primary is this slow?”
“This third-party endpoint lost its circuit breaker. What is the fallback if it goes dark during month-end close?”
“The schema drops legacy_customer_id. Who still reads it, and what is the cutover evidence?”
“You added a retry with jitter around a payment capture. Which failures are safe to retry, and which are not?”

The developer types a short answer or speaks it. The agent is responsible for structure, links, and prose. The human is responsible for the sentence that will not exist anywhere else.

Question selection is the product. A gate that fires on every pull request becomes the new theater. A gate that never fires misses the knowledge you needed. The rule is: interview on changes that alter failure modes, data meaning, external contracts, or irreversible operations. Everything else is captured ambiently and synthesized without bothering anyone.

If the answer is “I don’t know,” that is still an asset. Record the gap, tag the owner, and make the gap visible on the coverage map. An honest hole is more useful than a fabricated paragraph.

Layer 3 — Continuous synthesis

The agent is a living historian for the system, not a one-shot writer.

It continuously joins three things:

The current structure (what the code and config say)
The accumulated intent snippets (what humans said, and when)
The history of change (what used to be true)

From that join it maintains a searchable internal knowledge base: service pages, decision timelines, generated diagrams, dependency maps, and runbook skeletons. Pages are rebuilt when the graph they describe moves. Stale claims are flagged, not silently left to rot.

Synthesis must never pretend to be omniscient. Every generated claim should carry provenance: this paragraph came from commit abc123, ticket PAY-441, and an answer by Jordan on 2026-09-12. Claims without provenance are displayed as inferences and ranked lower in search.

The knowledge base is a derived view. The source of truth is the repository plus the intent records. If the wiki disagrees with the code, the code wins and the wiki is marked stale. That single rule ends most documentation theater by itself.

Layer 4 — Verification, coverage, and attestation

An unverified agent is a fluent liar. Leadership will—and should—reject a “living system” that cannot answer “says who, as of when?”

This layer is what makes abolition politically possible.

Human review of material synthesis. High-risk changes produce a documentation delta in the same pull request as the code. The author is not asked to write the page. They are asked to accept, edit, or reject the agent’s draft. That is minutes, not hours, and it keeps a person on the hook for meaning.

Freshness and confidence. Every page carries a freshness score (how recently the underlying graph changed versus how recently synthesis was rebuilt) and a confidence score (how much of the page is attested intent versus inferred structure). Search results show both. A beautiful page with low confidence is not presented as fact.

Coverage map. Leadership stops asking “is there a document?” and starts asking “which services have unexplained failure-mode changes in the last 90 days?” The map lists:

Services with no owner
Changes that required an interview and did not get one
Intent records that contradict current code
Runbooks that reference deleted dependencies
Controls with no mapped snapshot

Attested snapshots. When someone needs a static object—an auditor, a customer, a board pack—the system freezes a snapshot: the synthesized view, the underlying intent records, the commit range, the model or agent version, and a human attestation. That snapshot is the compliance artifact. The living page remains free to evolve.

This is the substitute for the neat checklist. It is stricter than the checklist, which is why it can replace it.

A walkthrough

A developer opens a pull request that raises a database parameter and removes a retry around a vendor API.

Ambient capture notices both changes, links them to the ticket “month-end timeouts,” marks the existing runbook paragraph on vendor retries as stale, and classifies the diff as high-risk because it alters a failure mode on a payment path.

Before merge, the agent asks two questions in the pull request:

Why this parameter, and what is the upper bound you are unwilling to cross?
If the vendor endpoint dies during close, what happens to in-flight captures?

The developer answers in four sentences. The agent writes a decision record, updates the service page, rewrites the runbook branch for vendor outage, and attaches provenance. A teammate reviews the code and the doc delta together. Merge produces both the behavior change and the knowledge change.

Six months later the developer leaves. The new owner does not inherit a template. They inherit a page that is current, a decision timeline that includes those four sentences, a coverage map that does not show an unexplained hole, and a search box that can answer “what is the fallback if the vendor dies?” without paging someone who no longer works there.

That is the entire point of the architecture. Not prettier docs. Survivable knowledge.

What this does not replace

Abolishing theater is not a license to abolish promises.

Keep human-authored, carefully reviewed documents when the artifact is the commitment:

Customer contracts and SLAs
Security white papers that make claims to outsiders
Regulated design-history files and validation protocols
Policy that creates legal duties
Incident reports whose audience is a regulator or a court

Those are not descriptions of a system. They are speech acts. An agent can draft them from the living base. A human still has to mean them.

Also out of scope for full automation: tacit knowledge that never touches the repo—how a particular customer is actually billed, which “unused” table is load-bearing for finance, why a cron job is named after a joke from 2019. Ambient capture will not invent that. The two-question interview is how you harvest it when a change finally brushes against it. Exit interviews should be treated as a last-chance interview pass over the person’s owned graph, not as a separate HR form.

Failure modes, and how the design absorbs them

Fluent error. Generated prose can be wrong in ways that look finished. Mitigation: provenance on every claim, confidence scores, doc deltas in the pull request, and a rule that operational runbooks with low confidence cannot be the primary pager instruction.

Garbage in. Commit messages like “fix” and ticket titles like “bug” starve the synthesizer. Mitigation: the interview exists exactly for this. Also, mild social pressure works: teams that write one-line intent in the PR description get fewer interview interrupts.

Interview fatigue. If every lint fix asks two questions, developers will type “n/a” and you will have rebuilt the template. Mitigation: strict escalation rules, skip-lists for known-noisy paths, and a budget—interviews per team per week, visible to the team, treated as a product metric.

Security and privacy. An agent that reads repos, tickets, and configs will see secrets, customer data, and unreleased strategy. Mitigation: same controls as any other developer tool—scoped tokens, no training on customer content if that is your policy, redaction of secret stores, and synthesis that cites but does not copy credentials.

Political answers. People will sometimes explain a change in the way that survives review rather than the way it happened. Mitigation: you already have this problem in templates. The difference is that the answer is timestamped next to a diff, which makes later contradiction cheaper to detect.

Leadership theater in a new costume. A coverage dashboard can become the new box to check. Mitigation: measure outcomes that hurt when they are fake—time for a new owner to ship a safe change, time to find a fallback during an incident, number of pages that contradict production. If those do not move, the dashboard is decoration.

What non-technical leadership is actually asking for

The closing fear is the right one. If this model became standard, would corporate leadership accept the loss of neat, predictable compliance checklists? Or would the urge to tick a static box win?

They will not “learn to trust AI.” They will accept a replacement that still buys the properties the checklist was a proxy for.

The checklist was never about typography. It was about:

Completeness — every important system has been described
Accountability — a name is attached to a claim
Point-in-time truth — we can show what we believed on a date
Comparability — artifacts look enough alike that a reviewer can scan them
Blame and defense — if something goes wrong, there is a paper trail

A dynamic, agent-maintained system can provide all five, if you design for them:

Completeness becomes the coverage map.
Accountability becomes named intent records and review on the doc delta.
Point-in-time truth becomes attested snapshots.
Comparability becomes a stable schema for service pages and decision records—generated, not filled in by hand.
The paper trail becomes an immutable log of diffs, answers, model versions, and attestations.

The static box should lose when those substitutes exist. It will win when engineers offer only a vibe: “the wiki is living now.” That offer is not serious, and leadership is right to reject it.

The political bargain is therefore explicit. Engineering stops performing templates. Leadership stops treating a page’s existence as control effectiveness. Both sides inspect the same objects: coverage, freshness, unanswered interviews, and snapshots you could hand to an auditor without lying.

How to adopt this without a grand program

Do not start with a platform rewrite. Start with one production system that already hurts when people leave.

Pick a bounded service with real operational risk and at least one recent departure or rotation.
Turn on ambient capture for that repo, its infra definitions, and its tickets. Produce a change graph before you produce prose.
Write the escalation rules for interviews. Put the questions in the pull request, not in a separate portal.
Require a doc delta on high-risk merges. The agent drafts; the author accepts or edits. No merge of the risk class without that review.
Publish a coverage map for that service only. Show holes in public, inside the team. Fix the holes that would injure a new owner.
The first time someone asks for a compliance packet, generate an attested snapshot from the living base instead of opening the old template. If the snapshot is insufficient, that is a requirements bug in the snapshot, not a reason to revive the ten-page form.
Measure the thing the theater was faking: hours from “you own this now” to “you shipped a safe change,” and minutes to find a fallback during a drill.

If those numbers do not move, you have built a more expensive stage set. Shut it off. If they move, expand the graph—adjacent services, shared platforms, the paths that actually fail at 2 a.m.

The human policy that must travel with the tools is small enough to write on a card:

We do not reward the existence of documents. We reward current, attributed answers to operational questions. The template is not a deliverable.

The paradigm worth doubling down on

The paradigm that does not work is this: knowledge is a document a person produces in advance, in a standard shape, so that an organization can feel prepared for absence.

The paradigm that does work is this: knowledge is a maintained property of the system. Structure is observed. Intent is elicited in the smallest possible interrupt. Synthesis is continuous. Trust is earned with provenance, coverage, and snapshots—not with a signature on a blank form.

Developers will explain how their systems work when the explanation is the work, not a costume they put on after the work. Leadership will let go of the costume when they are handed something that can survive an audit and a resignation on the same week.

Someone is going to leave an organization tomorrow. The only open question is whether they leave behind a ritual, or a record.