Binder Documentation Standard¶

Use this standard to keep the schoolbus binder coherent as it grows. The binder should feel like a field notebook plus protocol anatomy plus systems-textbook reasoning. It should not feel like enterprise SDK documentation, a standards mirror, or architecture theatre.

Reader Page Contract¶

Start from the protocol page template. A reader-facing protocol page should teach the inspection move before it teaches the repository. The main path is not a pasted review checklist, support policy, atlas record, or roadmap note.

Use this order unless a reviewer records a page-specific reason to deviate:

1. # Protocol Name
2. One-sentence learning promise
3. Compact status strip
4. ## A Concrete Artifact
5. ## Inspection Trap
6. ## Worked Decode
7. ## What The Evidence Supports
8. ## What The Evidence Does Not Support
9. ## Field Layout / Anatomy
10. ## Visual Model
11. ## Timing And Authority
12. ## Failure And Ambiguity
13. ## Python Model
14. ## Source Notes
15. ## References

Every page must help the reader answer five questions: what evidence appears, how far the artifact can be decoded, which assumptions enable that decode, where meaning comes from, and what a passive observer could overclaim.

Use the compact status strip for only reader-relevant posture:

Do not put support-tier explanations, promotion labels, atlas metadata tables, planned APIs, or roadmap commitments in the first-screen reader path.

Fold identity, operational context, and "why this exists" into the learning promise, artifact, inspection trap, and decode. Show the artifact before naming the likely overclaim so the page's durable contract matches the artifact-first reader promise. Framing is useful only when it helps the reader inspect the artifact safely.

Reviewer And Promotion Contract¶

The hard promotion gate lives in the final page checklist. It is a review surface, not prose to paste into protocol pages. Keep support tiers, review labels, source-quality rubric details, atlas source inventories, and future implementation posture in review, governance, roadmap, or shared trust/provenance pages.

Canonical Callouts¶

Use MkDocs admonitions consistently. Do not switch between HTML admonitions, local caveat boxes, and trailing caveat prose.

!!! note "Synthetic"
    Synthetic offline sample for explanation; not a real operational trace or live-system instruction.

Use this for synthetic frames, transactions, traces, diagrams, captures, description snippets, and file summaries.

!!! note "Simplification"
    State exactly what is simplified, omitted, or page-local.

Use this for toy dictionaries, field-boundary diagrams, omitted electrical detail, simplified timing, and partial current examples. Do not use it to present a planned API as current reader-facing functionality.

!!! important "Semantic authority"
    Bytes rarely explain themselves. Name the source that turns evidence into meaning.

Use this for DBC databases, J1939 PGN/SPN definitions, ARINC label tables, Modbus register maps, UDS service/DID catalogs, LIN LDFs, CANopen object dictionaries, MDF channel metadata, and similar sources. Prefer a page-specific authority statement over repeating this exact wording.

Draft Vs Final Copy¶

Use draft-structure-only explicitly when a field-note or appendix page has the right headings but still lacks page-specific artifact depth, observer consequence, or ambiguity. Use draft-core-lab for Core Lab scope pages that are planned as first-class teaching surfaces but are not yet promoted to final copy. It is better to publish an honest draft than to make a template-complete page look final.

Source Confidence Labels¶

Visual Model Rules¶

Use the smallest visual that teaches a real inspection move:

Place visuals after the worked decode unless the visual is necessary to understand the artifact before decoding. The usual sequence is artifact, decode, field anatomy, then a visual that rewards the reader with timing, authority, or observer structure.

Every visual must answer at least one of these questions:

• What does the artifact look like?
• How does timing work?
• Who has authority to speak or assign meaning?
• How does arbitration or scheduling work?
• How does semantic layering work?
• What can a passive observer infer?
• What ambiguity or failure mode becomes visible?

If the answer is "it looks nice," remove the graphic.

Semantic-Authority Rule¶

When a page's core lesson is semantic authority, give that idea enough room to teach. A CAN payload is not wheel speed until a DBC or equivalent source says so. A J1939 PGN is not yet an SPN value. An ARINC label is not yet an aircraft parameter. A Modbus register is not yet pressure. An MDF channel value is not credible unless metadata and capture provenance are credible.

Strong pages show at least one wrong-authority case so readers see how valid-looking bytes produce plausible false values.

Observer-Reasoning Rule¶

Every Core Lab page and every page promoted to final copy must state:

• what a passive observer can infer,
• what remains unknowable,
• and which timing assumptions matter.

The shared inspection path lives in the binder foundations. Do not paste a generic version of it into every protocol page. Add a page-specific visual only when it teaches the page's artifact, timing, authority, ambiguity, or observer reconstruction.

The shared path is:

Citation Rules¶

Use canonical atlas metadata for names, scope, document numbers, and source notes. Use public tooling docs for runnable workflows. Use vendor tutorials as explanatory cross-checks. Do not copy paywalled standards text, cite unofficial mirrors as authority, reproduce large tables, or imply conformance.

For final-copy pages, add a compact claim-level source table near Source Notes when the page makes several kinds of claims:

References should be grouped:

Public Sources¶

Use official pages, standards-owner summaries, public explainers, and tooling reference with short purpose notes.

The hard page review gate lives in the final page checklist.