Documentation style guide and audit standard

Overview

This document is the single source of truth for documentation style, structure, and quality checks across docs/. Use it for both human review and LLM-driven conformance checks.

  • Goal: keep all docs predictable, readable, and auditable over time.
  • Scope: all HTML documents under docs/ plus index pages and redirect stubs.
  • Related policy: ADR 0001, ADR 0018, ADR 0024, ADR 0026.

Global style rules (all document types)

  • Language: English, clear engineering prose, no slang, no hype.
  • Tone: neutral and directive; describe what is required, optional, and prohibited.
  • Tense: present tense for current behavior and policy; future tense only for planned work.
  • Heading case: sentence case for section headings; keep labels short and explicit.
  • Formatting: one primary topic per <section class="card">.
  • Terminology: use stable terms consistently (for example: "OpenAPI contract test", not variants).
  • Links: link by destination name (for example: ADR 0027, Runbook: Tests failing).
  • Commands and paths: wrap in <code>; use copy-paste-safe command examples.
  • Lists: use ordered lists for procedures and unordered lists for policies/reference.

Plain language (readability)

Docs should be easy to read for engineers who use English as a second language. Stay formal and precise, but prefer simple wording and short sentences over ornate or academic style.

  • Sentence length: aim for one main idea per sentence; split long chains with semicolons into two sentences.
  • Vocabulary: use common terms (e.g. “use”, “show”, “end”) instead of heavy synonyms when both are accurate.
  • Jargon: keep necessary technical terms; define acronyms on first use in a page ( plus title or a short gloss).
  • Voice: prefer active voice for steps (“Run make verify”) and passive only where the actor does not matter.
  • Nouns: avoid stacking long noun phrases; rephrase with a short verb (“The pipeline runs tests” not “The test execution phase of the pipeline”).
  • Consistency: when you simplify a hub or index, apply the same pattern to similar rows (same grammar, same level of detail).

Rolling updates: apply this section when editing any page; large legacy pages (older ADRs, long internal specs) can be updated in smaller PRs over time.

Required page skeleton

All non-redirect pages should follow this baseline skeleton.

  1. <h1> page title.
  2. <div id="docs-top-nav"></div> top navigation mount.
  3. First content card: either Overview or Status (document type dependent).
  4. Body cards grouped by one topic per card.
  5. <section id="page-history" class="card"> with a Page history table (see Page history).
  6. <div class="docs-inpage-toc-mount" data-inpage-toc="auto"></div> near end of <main>.

Redirect pages are the only exception: short "Page moved" card plus canonical link.

Docs frontend contract (required mounts and attributes)

This section defines the required HTML mounts and data-* attributes for shared docs UI features. Treat it as a stable frontend contract when creating or reviewing hand-written docs pages.

Feature Required markup Notes
Top navigation and quick actions <div id="docs-top-nav"></div> Mount for top nav, quick actions launcher, and command palette shortcuts.
Page editors widget <div id="docs-page-meta-mount" hidden></div> + data-maintainer-ids on <body> Shows avatar stack by default; clicking Page editors reveals full maintainer list.
Portal people listing <div id="portal-people-mount"></div> Used on internal/portal/index.html; includes group sections, sort, counts, and skeleton state.
Profile maintained pages <div id="portal-maintained-mount"></div> + data-person-id on <body> Used on internal/portal/people/*/index.html; includes pagination and skeleton state.
Auto in-page TOC <div class="docs-inpage-toc-mount" data-inpage-toc="auto"></div> Required for docs design checks; should be near the end of <main>.

Script dependencies for this contract: docs/assets/docs-nav.js, docs/assets/docs-portal-data.js, and docs/assets/docs-internal-meta.js. If a page omits one of these mounts/attributes, the corresponding UI feature should be considered disabled by design.

Document-type matrix

Type Primary purpose Must include
ADR Decision and rationale Status, Context, Decision, Consequences, Alternatives, change history
RFC Implementation-level specification Status, Goals/non-goals, architecture/flow, operations/troubleshooting
Runbook Incident triage and recovery procedure Symptoms, impact, pre-checks, step-by-step recovery, validation, escalation
How-to Task-oriented instructional guide Prerequisites, ordered steps, verification, related links
Internal API page Engineering narrative of behavior and operational meaning Contract summary, business rules, technical flow, error behavior, references
Audit report Assessment against standards and references Method, scored mapping, findings, mitigations, residual risk, review date
Index/hub Navigation and orientation Overview card, table/list of documents, concise "what this covers" descriptions

Minimal templates by type

ADR template baseline

  1. Status
  2. Context and problem statement
  3. Decision
  4. Consequences and trade-offs
  5. Alternatives considered
  6. References
  7. History

RFC template baseline

  1. Status
  2. Goals and non-goals
  3. Architecture or data flow
  4. Implementation details
  5. Operational guidance and troubleshooting
  6. Change management

Runbook template baseline

  1. Incident definition and trigger conditions
  2. Immediate safety checks
  3. Triage checklist
  4. Recovery actions (ordered)
  5. Post-recovery validation
  6. Escalation and owner handoff

Naming and linking conventions

  • File names: lowercase kebab-case with numeric prefix where series requires ordering (for example ADR/RFC/Runbook).
  • Operation page names: HTTP method plus path pattern (for example post-api-v1-user.html).
  • Link labels: keep style stable per index (for example always ADR 00XX, not mixed with Open ADR 00XX).
  • Index descriptions: one sentence, same grammatical style across rows.

Page history

Every hand-written HTML page must end with a Page history card (before the in-page TOC mount). Use one row per substantive edit (skip trivial typo-only fixes). In Author, use a link to the maintainer’s Employee portal profile when it exists (<a href="…/internal/portal/people/<slug>/index.html">…</a>, path relative to the current page). Use an em dash (—) when the author is unknown for older rows.

Date Change Author
Required Page history for all hand-written docs: table columns Date, Change, Author; assessment reports use 5. Page history / #5-page-history. Ivan Boyarkin

Markup: <section id="page-history" class="card">, optional <div class="docs-table-scroll" role="region" aria-label="Page history">, <table class="docs-page-history">, dates as <time datetime="YYYY-MM-DD">. Author cells that name a person should use <a> to their portal profile (see scripts/link_page_history_authors.py for Ivan Boyarkin baseline rows). Numbered assessment reports may use id="5-page-history" and heading 5. Page history instead.

Audit protocol for documentation changes

Use this protocol for every docs PR and for periodic audits.

  1. Run quality gates: make docs-fix, make docs-html-check, and project-required checks.
  2. Verify links and navigation paths for all changed/added pages.
  3. Verify section structure against this standard for the affected document type.
  4. Check terminology consistency against nearby index/hub pages.
  5. Confirm changelog and cross-links were updated when policy/process changed.
  6. Record deviations and remediation in audit notes or PR checklist.

LLM conformance checklist (copy/paste)

Use this checklist when asking an LLM to review docs changes.

Validate changed docs against docs/internal/front/documentation-style-guide.html.
              Return:
              1) Violations grouped by severity (critical/major/minor).
              2) For each violation: file path, violated rule, short evidence, concrete fix.
              3) Missing required sections by document type.
              4) Terminology inconsistencies (same concept, different naming).
              5) Broken or suspicious links.
              6) Final pass/fail verdict and residual risks.

Governance and updates

  • Any style-rule change must be updated in this page first, then reflected in related guides.
  • If a rule affects architecture/process, update the relevant ADR/RFC in the same PR.
  • When uncertainty exists, this document wins over local wording patterns in individual pages.