Standard-004: Documentation Audience Standard

Status note (2026-03-18): Last edited 2026-03-18 · Retain indefinitely as an engineering standard.

Formerly ADR-027. Reclassified as an engineering standard to keep ADRs scoped to architectural or contract decisions.

Status: Active

1. Purpose

This standard keeps documentation audience-first while making guarantee/assumption language precise, mode-specific, and reviewable.

2. Normative language

The key words MUST, SHOULD, and MAY are to be interpreted as described in RFC 2119.

3. Scope and entry-point taxonomy

An entry point is any page that users are expected to open first for a task, workflow, or conceptual understanding. Entry points are grouped into three tiers:

Tier

Page types

Primary audience goal

Tier 1

README, landing pages, decision-tree pages, 60-second pages

Fast orientation and next step

Tier 2

Quickstarts, task pages, playbooks

Execute a concrete workflow correctly

Tier 3

Foundations, reference, contributor-facing semantics pages

Understand formal semantics, assumptions, and limits

4. Audience-first structure requirements

  1. Documentation navigation MUST start with getting-started and audience hubs (practitioner, researcher, contributor/maintainer) before deep architecture.

  2. Tier 1 pages MUST stay brief and action-oriented; they are not the place for full semantics prose.

  3. Tier 2 pages MUST include runnable guidance for the task they cover.

  4. Tier 3 pages MUST hold the full semantics and non-guarantees detail.

  5. Every entry-point page MUST include an explicit tier label at the bottom of the page in the form Entry-point tier: Tier 1|2|3.

5. Guarantees/assumptions policy (tiered and mode-specific)

5.1 Global rules

  1. Guarantee language MUST be consistent with ADR-021.

  2. Pages MUST NOT collapse all model modes into one undifferentiated semantics statement.

  3. When semantics are stated, pages MUST separate these labels explicitly:

    • Calibration prerequisites

    • Mode-specific guarantees

    • Assumptions

    • Explicit non-guarantees

    • Explanation-envelope / feature-level interval limits

  4. User-facing pages (Tier 1 and Tier 2) MUST link first to an internal RTD semantics page under docs/foundations/ (or equivalent RTD route), not directly to raw GitHub ADR URLs.

  5. Tier 3 pages MAY additionally link directly to ADR-021 on GitHub.

5.2 Tier-specific requirements

Tier 1 (README / landing / decision-tree / 60-second)

Tier 1 pages MUST include a short semantics pointer (1-3 lines) that:

  • identifies that guarantees are mode-specific,

  • names the internal RTD semantics page, and

  • avoids detailed guarantee text.

Tier 1 pages MUST NOT include a full “Guarantees & Assumptions” block unless the page itself is designated Tier 3.

Tier 2 (quickstart / task / playbook)

Tier 2 pages MUST contain a mode-specific semantics note for the workflow shown. The note MUST specify the applicable mode:

  • Classification (Venn-Abers probability intervals)

  • Percentile/interval regression (CPS percentile intervals, no threshold)

  • Probabilistic/thresholded regression (CPS + Venn-Abers event probabilities)

For the chosen mode, the note MUST include concise bullets for:

  • calibration prerequisites,

  • guarantees,

  • assumptions,

  • explicit non-guarantees,

  • explanation-envelope / feature-level interval limits,

  • link to internal RTD semantics page.

Tier 2 pages SHOULD keep this note to about 6-12 lines total.

Tier 3 (foundations / reference / contributor semantics)

Tier 3 semantics-source pages MUST provide full mode-specific semantics coverage for all three modes and MUST include ADR-021-aligned non-guarantees, including:

  • dependence on exchangeability/distribution match,

  • no guarantee under drift or regime shift,

  • limits on propagated feature-level interval claims.

Other Tier 3 pages MAY stay scope-limited if they link to the canonical Tier 3 semantics-source page.

Tier 3 semantics-source pages MUST be the normative target that Tier 1 and Tier 2 pages link to.

6. Anti-bloat controls

  1. Tier 1 pages MUST NOT duplicate Tier 3 semantics prose.

  2. Tier 2 pages MUST NOT copy large semantics blocks from Tier 3; they should summarize only what is needed for the demonstrated mode.

  3. Repeated semantics text across multiple Tier 2 pages SHOULD be replaced with a shared include or a common RTD subsection.

7. Reviewer acceptance criteria (pass/fail)

A PR changing docs passes this standard only if all applicable checks pass:

  1. Tier identified: Each changed entry point has a bottom-of-page label indicating Tier 1, 2, or 3.

  2. Correct semantics depth:

    • Tier 1 has pointer-only semantics text.

    • Tier 2 has mode-specific note with required labeled elements.

    • Tier 3 semantics-source pages have full three-mode treatment; other Tier 3 pages provide scoped content plus explicit pointer to the semantics-source page.

  3. No semantics flattening: No page presents one combined guarantee statement for classification + interval regression + probabilistic regression.

  4. Non-guarantees present where required: Tier 2 and Tier 3 include explicit non-guarantees aligned with ADR-021.

  5. Link routing correct: Tier 1/2 link first to internal RTD semantics page; direct raw GitHub ADR links are only in Tier 3 or deeper technical pages.

  6. Audience-first preserved: Navigation and page order keep getting-started and audience hubs ahead of deep architecture references.

  7. Bloat check: Tier 1 remains concise; Tier 2 semantics note remains concise and scoped to the workflow mode.

8. Migration requirements by page type

  • README / landing / decision-tree pages: replace generic guarantee boxes with a short mode-aware semantics pointer and internal RTD link.

  • Quickstarts / task pages / playbooks: replace generic all-mode guarantee text with one mode-specific semantics note using required labels.

  • Foundations / reference / contributor semantics pages: consolidate full semantics, assumptions, and non-guarantees as the canonical source; include ADR-021 links as supporting references.

9. References

  • ADR-021: Calibrated Interval Semantics

  • ADR-012: Documentation & Gallery Build Policy

  • ADR-026: Explanation Plugin Semantics

  • STD-002: Code Documentation Standard

  • Capability Manifest: Capabilities manifest

  • Terminology Guide: Terminology Standardization