Documentation Writing Standard

You are learning a move

No active mission. Use this page to improve one real decision; reading alone is not proof.

How do you make the valuable next action the easiest clear action?

A documentation site is not a brochure. It is a living playbook and standards library that helps humans and agents move faster because someone closed a learning loop and retained the useful part.

This standard captures the discipline that makes that possible.

It serves the Tight Five by making purpose, proof, platform context, process, and accountable players legible enough to act on.

Education Writing Standard

Simplicity is the ultimate sophistication. Write the smallest truthful lesson that lets the intended reader understand the model, take one valuable action, and return evidence or a better question.

Use three controls together:

1. Clear language lowers the effort required to understand without lowering the evidence standard.
2. A critical checklist, prompt, template, example, or decision test makes the valuable action easy to begin.
3. One open next question uses the Zeigarnik effect to invite useful return, not vague suspense.

clear teaching → valuable action → easy instrument
→ observable result → better question → return and learn

Reader pit of success

Playbook Quality Gate v0.2 — PILOTING

Use this two-pause-point control for every substantive Playbook change: a new page, content change, or rewrite that changes meaning, evidence, page job, or discovery. Link, typo, and formatting maintenance receives proportional checks and records this gate as N/A.

The editor runs both pause points in DO-CONFIRM mode. A reviewer may stop publication when a required decision is unresolved, evidence is missing, or a gate fails. The editor corrects the earliest rightful page, template, procedure, navigation route, or deterministic check rather than adding another reminder.

Pause 1: preflight

Before drafting, confirm:

• the intended reader and useful change;
• the reader's independent state and the smallest valuable proximal move;
• the qualified support and contingent scaffold that can bridge that move;
• how support will fade and responsibility will return to the reader;
• the page job and template;
• the canonical home and disposition: keep, update, move, consolidate, replace, or delete;
• the evidence boundary, including what is demonstrated, inferred, or unknown;
• the required relationships and discovery route; and
• a snapshot of every internal and external destination on the page, with an explicit disposition for any destination the edit may remove.

Stop when the reader change, rightful owner, evidence boundary, or public route is unresolved. The kb-edit-playbook operational procedure owns the full editorial workflow; this checklist only protects its publication pause points.

Instructional composition contract

Every teaching page helps a learner make one move they cannot yet make independently, then gives responsibility back. Express these five decisions through the page job; do not force the terms or ritual headings into public prose:

1. Independent state — what the learner can already understand or do without this page.
2. Proximal move — the smallest valuable capability the learner can reach with support.
3. Knowledgeable support — the person, page, example, source, or instrument qualified to bridge that gap.
4. Contingent scaffold — the map, demonstration, guided attempt, feedback, and optional deeper detail matched to the learner's prior knowledge.
5. Fading and transfer — an independent attempt, teach-back, or second-context application that returns ownership to the learner.

The support is relative and bounded. A page, source, person, or AI is knowledgeable only for the claim and learner gap its evidence supports. When one fixed route would under-support a novice or overload an experienced reader, give the novice a map, worked example, and guided attempt while letting the experienced reader take the reduced-support route.

Vygotsky described the zone of proximal development through the difference between independent problem solving and problem solving with adult guidance or more capable peers. “More knowledgeable other” or “MKO” is later shorthand, not Vygotsky's original term. Wood, Bruner, and Ross later described tutoring support in problem solving, while a review by van de Pol, Volman, and Beishuizen identified contingency, fading, and transfer of responsibility as defining features of scaffolding. Support that ignores prior knowledge can also impede experienced learners through expertise reversal.

Pure hubs are exempt from this teaching contract because their job is routing, not instruction. They still orient the learner, give each route information scent, and preserve useful references.

External-reference stewardship

A reference is part of the teaching when it supplies evidence, canonical detail, a worked instrument, or a useful deeper route. Treat it as a durable relationship, not decoration:

• cite the original or canonical authority where possible;
• prefer a full https://doi.org/... destination for scholarly work;
• name the creator, title, and relationship to the claim;
• distinguish evidence sources, canonical detail, worked instruments, and further reading;
• keep important evidence inline with the claim, and add a Source Trail when fuller provenance helps; and
• never copy access-controlled or copyrighted content merely to preserve it. Retain a lawful citation and enough context to explain why the route matters.

Before compression closes, compare the destination snapshot with the edited page. A destination retained elsewhere on the same page needs no disposition. Every removed destination must be recorded as moved, replaced, archived with context under _production/research/, or approved for removal by a named human. Page deletion receives the same protection.

Pause 2: pre-publication

Run this six-item gate when the page and its route are ready for review:

• ACTION: One valuable next action is explicit.
• VALUE: The reader knows why it matters.
• EASE: The reader can begin with a usable instrument.
• TRUTH: Evidence, confidence, limits, and unknowns remain visible.
• CONTEXT: Links explain what the reader gains from following them.
• RETURN: The action produces evidence or a better next question.

A page fails this gate when it is easy to read but changes no action, offers an instrument without a valuable purpose, hides uncertainty, or ends without a return path. A checklist coordinates attention at a pause point; it does not replace the full method or professional judgment.

Verdict and receipt

Record one versioned receipt in the pull request:

Playbook Quality Gate v0.2
Page:
Reader:
Useful action:
Page job:
Checklist version: v0.2
Run status: USED | SKIPPED | OVERRIDDEN | UNTESTED
Verdict: PASS | CONDITIONAL | STOP | UNTESTED
Independent state:
Proximal move:
Knowledgeable support:
Contingent scaffold:
Fading and transfer proof:
Reference snapshot:
Removed-reference dispositions:
Gate evidence:
- ACTION:
- VALUE:
- EASE:
- TRUTH:
- CONTEXT:
- RETURN:
Binding gap:
Correction:
Minimal-reader evidence:
Checks:
Remaining risk:

Use the verdicts consistently:

• PASS — every applicable gate has observable evidence and no binding gap remains.
• CONDITIONAL — the change may proceed only with a named correction, owner, and review point.
• STOP — a failed gate, unresolved preflight decision, or unacceptable risk blocks publication.
• UNTESTED — the gate was not run or lacks enough evidence to judge.

A skipped, overridden, blank, failed, or untested gate cannot produce PASS. Missing evidence is evidence of an incomplete check, not permission to infer a positive result.

Pilot and review

Retain each run in its pull request. Count this installation change as run one only if a minimal reader can identify the standard's purpose, required action, truth boundary, and next route from this page alone.

Review the control when any of these happens:

• five substantive runs span at least three page jobs;
• the same ambiguity appears twice;
• a page-type or publication contract changes; or
• a process or platform change makes a gate obsolete.

On the fifth qualifying run, an approving human maintainer records ADOPT, REVISE, or RETIRE. ADOPT promotes the gate to v1.0. REVISE increments v0.x and freezes a new review point. RETIRE removes the operating pointers; Git history keeps the pilot evidence. Five completed runs establish whether the control is usable. They do not prove better writing or reader outcomes; that claim requires later comparable reader evidence.

The Checklist method owns checklist design, pilot interpretation, and revision. Use it when a recurring defect should change the earliest rightful process or platform control.

Source Trail

• L. S. Vygotsky, Mind in Society: The Development of Higher Psychological Processes — the source for independent capability versus capability under adult guidance or collaboration with more capable peers. WorldCat record
• David Wood, Jerome S. Bruner, and Gail Ross, “The Role of Tutoring in Problem Solving” — the early tutoring study that introduced the scaffolding metaphor in this instructional lineage. PubMed record
• Janneke van de Pol, Monique Volman, and Jos Beishuizen, “Scaffolding in Teacher–Student Interaction: A Decade of Research” — the review supporting contingency, fading, and transfer of responsibility as key characteristics. https://doi.org/10.1007/s10648-010-9127-6
• Slava Kalyuga, Paul Ayres, Paul Chandler, and John Sweller, “The Expertise Reversal Effect” — evidence that guidance useful to novices can become redundant or harmful as expertise grows. https://doi.org/10.1207/S15326985EP3801_4
• Crossref, “Display guidelines for Crossref DOIs”; W3C, “Cool URIs don't change”; and Perma.cc, “About Perma.cc” — stewardship guidance for persistent identifiers, durable destinations, and reference rot. Crossref, W3C, and Perma.cc

The minimal-reader test

The gate above is opinion until tested. The standard's falsifier: give the page — and nothing else — to the least capable reader it claims to serve (a small agent is the cheapest stand-in). If that reader completes the page's action and reaches the stated outcome, the page passes. If it demands more effort, skill, or intelligence than the page assumes, the page is not finished — compress or clarify, then retest.

End on the Action Ladder

Every page that teaches an action closes with up to three rungs, strongest honest rung first:

1. Do it now — the checklist, prompt, or template on this page. Free, self-serve, no lock-in.
2. Do it with the tool — when a live capability performs the action better, link the journey that teaches and offers it (see BOaaS).
3. Vote to build — when the tool does not exist yet, link the journey where a reader can register demand. A vote is a located gap with coordinates, not a promise.

Rung 1 is never optional. Rungs 2 and 3 use public journey routes only — never private repository or skill paths.

Emotion → Reason → Path

Public landing pages and the Playbook have different jobs in one truthful handoff:

src/pages/** → emotion, possibility, identity, choice
/playbook/** → reason, evidence, method, practice, return

A landing page earns attention through truthful emotion, identity, stakes, and possibility. It helps a named reader recognise what matters and choose a useful direction. The canonical Playbook lesson or diagnostic then earns confidence through reasoning, evidence, reusable practice, and a return path.

Use this contract:

• Every emotional public claim hands off to a canonical lesson or diagnostic that explains and bounds it.
• A landing page does not duplicate the full teaching. A Playbook page does not become disguised sales copy.
• Emotion may create pull. It may not manufacture urgency, suppress cost, or inflate proof.
• The intended beneficiary, valuable change, and human authority stay consistent across the handoff.
• The destination makes the next action, evidence boundary, and useful return visible.

The handoff fails when the emotional claim has no explanatory owner, the destination changes who benefits, or the Playbook is used to hide a commercial claim inside public teaching.

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.

Page-Level Wisdom Transfer

The Wisdom Transfer Standard is the broader cross-interface contract. This page implements it for documentation. The instrument below helps a writer teach; it does not replace the Purpose, Integrity, System, Knowledge, Teaching, and Transfer gates.

Teaching and Coaching Tight Five

Research becomes education only when a learner can understand the model, act without hidden context, and show that the learning transfers. Use this Tight Five to turn researched knowledge into independent action:

1. Map — explain the critical idea, system, and relationships in one clear model.
2. Movement — give the learner a bounded action, protocol, or decision they can complete.
3. Evidence — distinguish facts, hypotheses, uncertainty, and what would change the claim.
4. Compression — remove every word, section, and example that does not improve understanding or action.
5. Transfer — require teach-back, independent application, or a second example to show that learning survived.

Compression means maximum useful information per sentence. It does not justify removing evidence, context, uncertainty, or safety guidance that changes a decision.

Choose the right mode

Mode	Use when	Responsibility
Teacher	The learner lacks the map	Explain the model, demonstrate it once, then check understanding.
Coach	The learner has the map but is stuck	Provide the smallest useful scaffold, then return the decision and action to the learner.
Researcher	The available evidence is incomplete	Record sources, contradictions, uncertainty, and a falsifiable hypothesis before prescribing.

The Dream repository documents the reusable method and the bounded experiment. A field operator or Stackmates executes the experiment and returns evidence. Documentation does not authorize the repository or its writers to operate the systems they study.

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

Match the contract to the page job

A substantial educational page makes these elements easy to find, but their form and depth follow the page job:

• An answer-first statement of what the reader will understand or do.
• The intended learner and required prior knowledge.
• The principle, model, or relationship map.
• Numbered instructions when action is part of the job.
• One worked example.
• The evidence state, uncertainty, and a claim falsifier.
• The decision or action the page supports, using page_job when the page type alone is too broad.
• The conditions for using the page and the conditions for choosing another authority.
• A review signal that names the observable change that would invalidate or reopen the guidance.
• Failure modes and safety boundaries.
• Proof of learning through teach-back, independent application, or transfer to a second example.
• One useful next action and typed contextual links that state why the destination matters.

Do not turn this list into nine ritual headings. Apply it by page type:

Page job	Required teaching emphasis
Hub	Orient the intended reader, expose the choice, and route with link scent. Do not teach.
Reference	Support accurate lookup with definitions, evidence state, boundaries, and contextual links.
Explanation	Teach the map, show one example, name its limits, and ask for teach-back or transfer.
How-to	State the outcome and prerequisites, give numbered steps, show a worked run, and test output.

The contract passes when a learner can point to the map, choose the next action, state how strong the evidence is, and demonstrate learning without copying the page.

For technical references and runbooks, make the decision boundary visible before detailed procedure. State one supported decision, when the page applies, when it does not, the current evidence state, and the change that should trigger review. A decision record can preserve why a consequential choice was made; the current page should still expose when that choice is safe to reuse.

If a page owns an executable proof and fresh measurements exist, it may record the command, observed duration, measurement date, environment, and sample count. Never turn observed proof cost into a blocking budget or claim a percentile that was not measured.

Worked example: turn a claim into a lesson

Suppose research suggests that shorter feedback cycles improve a team's ability to correct work.

1. Map: draw action → observable result → comparison with setpoint → correction and explain each relationship.
2. Movement: ask the learner to run one low-risk task with a named setpoint and a same-day review.
3. Evidence: label the general claim as supported only by the cited field evidence; label the local result as unknown until measured. A comparable longer cycle producing faster, better correction would weaken the claim.
4. Compression: keep one example and the minimum safety boundary; remove history that changes neither understanding nor action.
5. Transfer: ask the learner to apply the loop to a second workflow and explain which signal would trigger correction.

The teacher demonstrates the first loop. The coach asks what blocks the learner's second loop and offers only the missing scaffold. The researcher records the comparison and updates the claim.

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.

Finish incompressibly

A touched /playbook page is not finished when the prose sounds good. It is finished when the page shape cannot be compressed further without losing the reader's next action.

Before close, the local strict gate checks the minimum shape:

• Frontmatter declares type.
• Hub pages orient and route: one-sentence opener, ## The Spine, ## Zoom Out, child links with scent, no teaching-heavy body.
• Know-how pages teach a reusable pattern, include ## Context, and expose action material, checks or signals, and failure modes.
• Normal /playbook pages do not leak inner-game paths, skill names, or repo-specific implementation details.

The post-edit hook still gives advisory writing feedback. Stop, commit, pre-push, and npm run docs:quality block on the strict page-shape failures for touched docs.

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

Changes my mind: a shorter or simpler standard produces more useful reader action and stronger returned evidence without weakening truth, context, or judgment.

Context

• Standards Index — choose the governing public standard.
• Standard Templates — start from the page shape that matches the reader's job.
• Naming Standards — settle durable names before polishing prose.
• Triad System Standard — the three-state shape every durable page resolves into: Reality, Dream, Bridge

Questions

Next question: What is the smallest truthful lesson that would change the reader's next action?

• When does sharing the learning process matter more than sharing the conclusion?
• How can someone apply the pattern without carrying all of its original context?
• What evidence should return after the reader acts?