Documentation Architecture

Status: Current Last modified: 2026-10-02 (commit 2d7e886b)

Principle: Centralized Book + Subsystem Satellites

User-facing and contributor-facing prose lives in mdBook (book/). The repo-level docs/ directory holds operator-facing material (release contract, versioning, code-signing, platform support, validation feature flags). Maintainers can also generate a local error-reference tree under docs/errors/ while working on diagnostics, but that output is not the canonical checked-in docs surface. Subsystem-specific working docs stay in place only when tightly coupled to files in that directory.

flowchart TD
    main["book/ (the unified Chatter mdBook)\nSurfaces: chatter, chat-format, architecture, contributing\nAudiences: users, integrators, contributors"]
    spec["spec/docs/\nSpec authoring guides"]
    errors["docs/errors/\nOptional local generated error reference"]
    api["cargo doc\nRust API docs (auto-generated)"]

    main -->|"links to"| spec
    main -->|"links to"| errors
    main -.->|"complements"| api

Where Documentation Goes

Rules

1. One canonical page per topic. No duplicate coverage across locations.
2. No crate-level docs/ directories. Architectural explanations go in the book. Crate API docs come from /// doc comments via cargo doc.
3. Satellites stay only when the audience is editing files in that directory. Spec authors need WRITING_ERROR_SPECS.md next to their specs. Everyone else reads the book.
4. Generated docs are build artifacts. Never hand-edit docs/errors/; just spec-check reports a hand-written file there as extra and fails. Regenerate with just spec-gen.
5. Historical docs go to project archive. Don’t keep old audit logs, investigation notes, or superseded proposals in the public repo.

Publication dates and content review

SUMMARY.md uses an HTML <a href="…">Git history</a> link to its own history; mdBook would interpret a Markdown link there as a chapter entry.

Last modified is publication metadata, not a certificate of content review. Book chapters use **Last modified:** 2026-10-02 (commit [2d7e886b](https://github.com/TalkBank/chatter/commit/2d7e886b)); the configured Git-date preprocessor renders the date and commit from that chapter’s history. Documents outside the rendered book, including SUMMARY.md, use a header linked to their own Git history, for example **Last modified:** [Git history](https://github.com/TalkBank/chatter/commits/main/CONTRIBUTING.md). Both forms follow ordinary edits and content-preserving squashes without a manual date sweep. Content review remains part of change review.

The date check admits the metadata header itself. A placeholder mentioned in the body, a non-book rendering placeholder, or a history link to another file does not exempt a document. Handwritten dates remain supported and checked against actual and prospective commit dates; update them from real date output when editing. Existing known-stale handwritten dates remain in the ratchet until their pages are reviewed and corrected.

One unified book

There is one mdBook for this repo at book/, titled “Chatter, TalkBank CHAT Toolchain”, organized by audience-first sections under book/src/:

One book.toml and one SUMMARY.md for the whole tree. Cross-section links resolve as ordinary in-book paths.

Diagram Authoring Rules (canonical)

Architecture and design documentation MUST include Mermaid diagrams. GitHub renders Mermaid natively; all mdBook builds have mdbook-mermaid enabled.

When to Create a Diagram

Add a diagram when documenting:

• Data flow pipelines (how data transforms through stages)
• Architecture boundaries (what owns what, who calls whom)
• State machines and lifecycles (valid transitions, terminal states)
• Decision trees (option routing, fallback paths)
• Type relationships (trait hierarchies, enum variants, ownership)
• Protocols (request/response sequences, IPC message flows)

If a page describes a pipeline, boundary, or decision flow in prose without a diagram, the page is incomplete.

Diagram Type Selection

The Seven Diagram Rules

These rules exist because a successor who has never met the team will read these diagrams to understand the system. Every rule directly addresses a documented failure mode that produces misleading diagrams.

1. Name every resource. Every node must have a specific name AND its type/role. Not "Cache", use "SQLite cache\n(talkbank-cache crate)". A reader must be able to grep the codebase for the node label and find it.
2. One concept per diagram. Each diagram tells one coherent story. When in doubt, split.
3. No conveyor belts for interactive flows. If two components exchange messages (request/response, IPC, HTTP), use sequenceDiagram. Reserve flowchart for genuinely one-directional data pipelines.
4. Show real decision points. Decision diamonds must use real function names, flag names, and condition expressions, not "check condition".
5. Include error and fallback paths. Every decision node must show what happens on failure. Mark optional paths with dashed lines (-.->).
6. Anchor to source locations. Architecture diagram nodes should include the crate, module, or file path in the label or in prose immediately below.
7. Never generate diagrams from source code without verification. Read the actual source files for every entity in the diagram; verify every node corresponds to a real module, function, or type; if you cannot verify a connection, omit it, gaps are better than lies.

Formatting Standards

• Node labels: ["Name\n(role or path)"] for multi-line
• Decision nodes: {"condition?\ndetail"} diamond syntax
• Edge labels: -->|"label"| target for all non-trivial edges
• Colors/styles: Do not use custom colors. Default Mermaid themes ensure consistent rendering across GitHub and mdBook
• Size limit: Keep diagrams under about 30 nodes. If larger, split into focused diagrams.
• Angle bracket escaping: Raw angle brackets in Mermaid labels (Arc<str>, Cow<str>, &str) trigger mdBook “unclosed HTML tag” warnings. Escape as <str> inside labels.

Placement

• Place each diagram inline, immediately after the prose paragraph that introduces the concept it illustrates.
• Every diagram must have a prose introduction explaining what it shows and why the reader should care.

This page last changed: 2026-10-02 (commit 2d7e886b). The whole book last changed: 2026-10-07 (commit 5e895791).