Documentation Writing Standard
A documentation site is not a brochure. At its best it is a living playbook + standards library — a vehicle for thinking that lets humans and agents move faster along their own critical path because someone else closed the loop already and wrote down what they learned.
This standard captures the discipline that makes that possible.
Writing Intent
Five intentions govern every page.
1. Share the learning process, not just the conclusions
- Show the questions, experiments, and failures that led to each standard.
- Make versioning explicit: what is Stable, what is Evolving, what is Experimental.
- Treat every doc as a snapshot of "the best we know so far," open to refinement.
A page that shows only the conclusion teaches nothing about how to reach it. A page that shows the path lets the next reader walk it faster — or take a better one.
2. Compress useful models so others can move faster
- Take patterns that work in practice and express them as clear mental models, checklists, and protocols.
- Bias toward concrete "how we actually do it" over abstract philosophy.
- For every page, ask: "What would have helped us two years ago to avoid wasted cycles?" Then write that.
Compression is the multiplier. A model that takes ten minutes to read but saves ten weeks of trial-and-error is the highest-value artifact a docs site can produce.
3. Make first principles legible
- Expose the core truths the rest of the work depends on: feedback loops, values → beliefs → control, compounding standards, sovereignty over data and intent.
- Tie every practice back to those truths so people can rebuild or adapt in their own context.
A practice without its first principle is a cargo cult. The first principle is what travels across contexts; the practice is one expression of it.
4. Serve humans and agents as equal citizens
- Write so a smart human OR a capable agent can decode the page and act correctly.
- Use plain language first, then formal notation when precision is needed.
- Assume readers will plug these docs into trusted execution environments where standards need to be machine-usable.
Two readers, one source of truth. If only humans can read it, agents will misroute. If only agents can read it, humans stop trusting it.
5. Preserve identity while staying readable
- Keep the canonical vocabulary — meta-language, packs, codes, dimensions — as the backbone.
- Wrap formal notation in short, clear, humane explanations so people reach depth without getting lost.
Readability is not the opposite of precision. It is the on-ramp to precision.
Target Reader
People and agents on a similar journey, who:
- Care about agency, sovereignty, and intention → action.
- Want to design better feedback loops in products, data, and teams.
- Are building or using agentic systems, protocols, or commerce platforms.
- Are willing to think deeply now so they can act quickly and decisively later.
If a reader is trying to design their own meta-language, map their data and content graph, or build agents that respect human intention, the docs should feel like well-lit shortcuts.
Doc Shape
Start simple, then go deep
| Layer | Content |
|---|---|
| 1 | One clear sentence: what this is and why it exists |
| 2 | A short section: when to use it and what problem it solves |
| 3 | Only then: the formal notation, tables, and protocols |
A reader who needs only the first layer should be able to leave with the answer. A reader who needs the third layer should be able to dive into precision without losing the thread.
Answer the same core questions
Every page lets a reader quickly see:
| Question | What it answers |
|---|---|
| Identity | What is this thing? How does it fit in the system? |
| Connection | What is it built on? What other docs or standards does it bind to? |
| Calling | What work is this trying to make easier or more meaningful? |
| Focus | Where does this apply and where does it not? |
| Purpose | How does using this doc move someone closer to fulfillment, not just efficiency? |
Pages that answer these questions in the same shape compound. Readers learn the shape once and re-use it forever.
Expose the critical path
Each doc shows:
- The minimum steps to get value from the idea ("do this first, then this")
- What to measure or observe to know it's working
- The most common failure modes and how to recover
A pattern without its failure modes is half-taught. The failure modes are where readers spend most of their time.
Tie back to the larger graph
Docs link out to:
- Related standards (foundational layers — meta-language, protocols)
- Related playbooks, PRDs, and worked examples that show the pattern in the wild
A reader can move from story → standard → implementation without losing context.
Our Promise
By writing documentation this way, the implicit promise is:
- To be honest about what works and what is still experimental
- To share structure, not secrets — enough that others can rebuild the ideas themselves
- To keep the docs live and evolving, updated as feedback loops teach more
What is not promised:
- That this path is the only way
- That everything is finished or polished
- That readers can skip doing the work — every reader still has to think and adapt for their own context
Key Takeaways
- A docs site is a living playbook + standards library, not a brochure
- The intent is to share the learning process and compress the patterns that work so others move along their own critical path faster
- Writing is plain first, formal second: clear orientation, then formal notation
- Every doc answers what it is, why it matters, when to use it, how to apply it, and how it links into the wider system
Questions
What makes a docs page worth writing at all?
- When does sharing the learning process matter more than sharing the conclusion?
- How do you compress a pattern so someone else can apply it without the full context?
- What is the minimum a page must answer to serve both a human and an agent correctly?
- How do you know when a doc is finished versus when it is just done for now?