How established standards, frameworks, and notations help us structure knowledge for humans and AI agents.
On October 2, 2026, Andrej Karpathy suggested several ways to make language-model output easier to understand. One was to ask for explanations in ASD-STE100, the controlled language developed for aerospace maintenance documentation. He also discussed diagrams, interactive HTML pages, and bespoke explainer videos.
The suggestion points toward a useful question: when an explanation is difficult to follow, would a different structure make the important parts easier to inspect?
In the same discussion, Grady Booch pointed to UML. Established modelling approaches already give us ways to describe systems and behaviour. There is a wider toolkit here, and much of it predates current AI agents.
Karpathy's post concerns people understanding AI output. We can extend that question in the other direction: how should we structure documentation that an agent will read before acting?
Two readers, overlapping needs
A person might open a document to learn why a system works a certain way. An agent might read it to implement a feature or follow a procedure. Both need consistent names, explicit conditions, examples, and a way to distinguish requirements from suggestions.
Their needs are not identical. A diagram can help a person grasp a boundary quickly, while an agent may need the editable diagram source or a textual account of the same relationships. A tutorial can guide someone through a learning experience, while a reference page provides facts for a specific task.
The objective is to choose a representation that exposes what the reader needs to know. Instructions, architecture views, and decision tables each make different things visible.
A polished paragraph can still hide the rules
Consider this invented workshop-registration policy:
Register people when places are available. Ask for an email address and put people on a waitlist when the workshop is full. Return the confirmation for someone who has already registered.
It sounds reasonable. But suppose an existing registration is submitted again when the workshop is full. Should the system return the existing confirmation or add the person to the waitlist? What if the repeat request has no email address?
The paragraph contains the ingredients of a policy, but its precedence is unclear. Shorter sentences alone will not resolve that.
For the example below, we will explicitly choose these rules: check for an existing confirmed registration first; require an email address only for a new registration; then check capacity. Returning an existing confirmation does not reserve another place. Adding someone to the waitlist does not reserve a place either.
Those are authored business rules for this example. They are not facts discovered by formatting the paragraph.
The toolkit already exists
These approaches address different problems. Some are standards; others are frameworks, models, or documentation practices.
ASD-STE100: make technical instructions precise. Simplified Technical English combines writing rules with controlled vocabulary. Its aerospace-maintenance origin matters: ambiguous instructions can have serious consequences. Consistent terminology and clearly separated actions are useful ideas to apply elsewhere. Asking a model for STE-inspired prose does not establish conformance to the complete specification.
Diátaxis: separate different documentation needs. Diátaxis distinguishes tutorials, how-to guides, reference, and explanation. Use it when a page tries to teach a newcomer, list every option, and explain design history at the same time. For the registration service, a how-to might explain how an organiser opens registration; a reference specifies the request fields; an explanation discusses the capacity policy.
C4: choose an architecture level. Simon Brown's C4 model provides system-context, container, component, and code views. Use it to explain where a registration service sits and how its parts relate. Start with the level needed for the question. A context diagram can show an attendee, the registration system, and an email provider without including every function or database column.
UML: select a view of structure or behaviour. UML is a standardised modelling language with several diagram types. A sequence diagram can expose interactions between a client, registration service, and database. A state-machine diagram can describe valid transitions. The question determines which view is useful; a generic request for a UML diagram leaves that choice unresolved.
Decision tables: expose combinations of conditions and outcomes. A table can show which rule applies when several conditions interact. Define what happens when rows overlap. A small teaching table is not automatically a complete executable decision model.
Architecture decision records: retain the reasoning. An ADR captures a consequential architectural choice, its context, and its consequences. Use one to record why a service chose a particular persistence or integration approach. It helps a future reader assess whether the reasons still apply.
One example, three representations
Return to the workshop policy. We can express the same chosen rules in three ways.
1. Instructions reveal the order
- Check for an existing confirmed registration.
- If one exists, return its confirmation. Do not reserve another place. Stop.
- For a new registration, check for an email address.
- If it is missing, request it. Stop.
- Check whether a place is available.
- If a place is available, confirm the registration and reserve one place.
- Otherwise, add the person to the waitlist without reserving a place.
This view makes the sequence explicit. A reviewer can trace a repeat request before reading the capacity branch. These are plain instructions inspired by clarity principles, not a claim of full ASD-STE100 compliance.
2. A process view reveals the branches
Existing confirmed registration?
├─ Yes → Return existing confirmation → Stop
└─ No → Email address supplied?
├─ No → Request email address → Stop
└─ Yes → Place available?
├─ Yes → Confirm and reserve one place
└─ No → Add to waitlist; reserve no place
The branching structure is easier to scan here. It also has a text equivalent in the preceding instructions, so the reader does not have to rely on the visual arrangement alone.
This is a lightweight process sketch. It does not show the architecture or the messages exchanged between services.
3. A decision table reveals the cases
Read from the first row down and apply the first matching row.
| First matching condition | Outcome | Additional places reserved |
|---|---|---|
| Existing confirmed registration | Return existing confirmation | 0 |
| New registration; email missing | Request email address | 0 |
| New registration; email supplied; place available | Confirm registration | 1 |
| New registration; email supplied; no place available | Add to waitlist | 0 |
Tracking places reserved gives a reviewer a concrete invariant to inspect: only a newly confirmed registration consumes another place.
A developer can turn these rows into test cases. An agent can be asked to propose cases against the table, with a person reviewing the result. Neither activity proves that the real system follows the rules.
Choose the structure by the question
For this registration system, the choice might look like this:
- How does an organiser open registration? Write a how-to guide with prerequisites and checks.
- Which fields does the request accept? Provide a reference with required fields, types, and examples.
- Where does the service fit? Start with a C4 context or container view.
- Which component calls which, and when? Consider a UML sequence diagram.
- What happens for each combination of conditions? Use a decision table with explicit matching behaviour.
- Why was this architecture chosen? Preserve the reasoning in an ADR.
Several approaches can work together. Diátaxis helps organise the documentation. A how-to can use consistent terminology. Its explanation can link to a C4 view and a decision record. The reference can include a rule table.
A more useful request to an AI assistant names the question and the constraints:
Rewrite this registration policy as ordered instructions and a decision table. Preserve every condition and exception. State the row-matching rule. List ambiguities separately instead of resolving them silently.
That prompt gives the reviewer something specific to check. It still requires a source policy and a decision about any unresolved ambiguity.
Structure helps; verification still matters
A clear table can encode the wrong policy. A sequence diagram can omit an authorisation check. A concise rewrite can remove a qualification that mattered.
Review at least three things independently: whether the content is correct, whether important cases are covered, and whether the intended reader can use it. Then check that the document still matches the implementation or process it describes.
Our example deliberately leaves production concerns outside its boundary: how existing registrations are identified, whether addresses are validated, how cancellations work, and what happens when two people request the final place concurrently. A useful document names those gaps. A real implementation needs further rules and checks.
Try the judgment
Suppose a colleague proposes this shortcut:
When the workshop is full, add every registration request to the waitlist.
Does it preserve the example policy?
Pause before reading on.
It does not. It changes the result for an existing confirmed registration. That person should receive the existing confirmation, even when the workshop is now full. The shortcut drops the precedence rule.
A second exercise is to ask where concurrency belongs. The decision table expresses the intended outcome, but a system design must explain how capacity checking and reservation stay consistent. That may require an interaction view, a transaction rule, and tests in addition to the table.
A field guide for learning, practising, and applying
The AI Output Field Guide brings 30 approaches together in an interactive learning resource. Each entry explains its history and original purpose, benefits and limits, suitable uses, an example, and primary references.
Readers can compare approaches, switch between representations of a worked case, try 90 short drills with explained answers, and take downloadable templates into their own work. The guide runs as a static website with no runtime LLM or model API calls. Bookmarks and exercise activity stay in the browser.
Start with one document that repeatedly causes questions. Identify what readers are trying to do, choose a representation that exposes the difficult part, and check what survives the transformation. The useful result is a document someone can understand, question, and act on.
AI disclosure: This article was drafted with AI assistance and reviewed against the linked sources and the field guide's implemented examples. The registration scenario is illustrative; no measured improvement in human comprehension or agent reliability is claimed.
Top comments (1)
The decision table bit stood out, especially the first-matching-row rule keeping a repeat registration from reserving another place.