Operating the Book as a Living Knowledge System

An online Markdown book about quantum operations should not behave like a static textbook. The field changes, hardware improves, APIs move, standards mature, and operational patterns are still emerging. The book itself needs an operating model.

This chapter defines the book as a living knowledge system: versioned, reviewed, source-backed, diagram-tested, and periodically pruned.

Diagram loads as you read

Operating the Book as a Living Knowledge System · Figure 1

View diagram source

flowchart LR
    Change[New field change] --> Intake[Intake issue]
    Intake --> Triage[Triage]
    Triage --> Draft[Draft update]
    Draft --> Review[Technical review]
    Review --> Build[Build checks]
    Build --> Release[Book release]
    Release --> Archive[Archive previous version]

Content layers

Diagram loads as you read

Content layers · Figure 2

View diagram source

flowchart TB
    Book[Book] --> Stable[Stable principles]
    Book --> Current[Current-state platform facts]
    Book --> Patterns[Operational patterns]
    Book --> Templates[Templates and schemas]
    Book --> Watch[Technology watch]

Stable principles change slowly: error budgets, evidence discipline, baseline control, and review gates. Current-state platform facts change quickly. Mixing these layers without labels causes decay.

Revision classes

Revision class	Example	Review requirement
editorial	wording, structure, typo	editor review
diagram	Mermaid correction or redesign	build check plus editor review
source refresh	API, vendor, standard update	source verification
technical change	new operating recommendation	domain expert review
template change	schema or runbook template	compatibility review
safety/security change	access, safety, compliance guidance	security or safety review

Diagram loads as you read

Revision classes · Figure 3

View diagram source

flowchart TD
    Change[Proposed change] --> Classify[Classify revision]
    Classify --> Editorial[Editorial]
    Classify --> Source[Source refresh]
    Classify --> Technical[Technical]
    Classify --> Template[Template]
    Classify --> Safety[Safety or security]
    Editorial --> Merge1[Editor merge]
    Source --> Verify[Source verification]
    Technical --> Expert[Expert review]
    Template --> Compat[Compatibility check]
    Safety --> Approval[Safety/security approval]

Source freshness

Every source-backed current-state claim should carry a review cadence.

Diagram loads as you read

Source freshness · Figure 4

View diagram source

flowchart LR
    Claim[Claim] --> Source[Source]
    Source --> Freshness[Freshness window]
    Freshness --> ReviewDate[Review-by date]
    ReviewDate --> Refresh[Refresh or retire]

Vendor API claims may require review every quarter. Foundational standards may require annual review. Physical principles may require review only when the surrounding explanation changes.

Diagram governance

The book uses Mermaid because system diagrams are part of the argument. A diagram can be wrong even when it renders.

Diagram loads as you read

Diagram governance · Figure 5

View diagram source

flowchart TB
    Diagram[Diagram] --> Syntax[Syntax valid]
    Diagram --> Semantics[Semantics accurate]
    Diagram --> Scope[Scope clear]
    Diagram --> Accessibility[Readable labels]
    Diagram --> Maintenance[Still current]

A diagram should name the abstraction level. A circuit diagram, control-plane diagram, and governance diagram should not be blended unless the chapter is explicitly explaining how the layers interact.

Release notes

Each release should summarize what changed and what was not verified.

Illustrative listing · yaml

release: v20
scope:
  chapters_added: 147-154
  appendices_added: AG-AH
checks:
  navigation_targets: passed
  mermaid_blocks_counted: passed
  references_defined: passed
known_limits:
  - chapters need copy edit
  - examples are illustrative unless explicitly source-backed

Diagram loads as you read

Release notes · Figure 6

View diagram source

flowchart LR
    Release[Release] --> Added[Added]
    Release --> Changed[Changed]
    Release --> Fixed[Fixed]
    Release --> Sources[Sources refreshed]
    Release --> Limits[Known limits]

Deprecation

A living book needs deprecation, not just accumulation.

Diagram loads as you read

Deprecation · Figure 7

View diagram source

stateDiagram-v2
    [*] --> Active
    Active --> Questioned: source stale or practice disputed
    Questioned --> Active: refreshed
    Questioned --> Deprecated: superseded
    Deprecated --> Archived: retained for history

Deprecated guidance should remain visible with a reason. Silent deletion removes institutional memory.

Maintainer roles

Diagram loads as you read

Maintainer roles · Figure 8

View diagram source

flowchart TB
    Maintainers[Maintainers] --> Editor[Editor]
    Maintainers --> Technical[Technical reviewer]
    Maintainers --> Source[Source curator]
    Maintainers --> Diagram[Diagram maintainer]
    Maintainers --> Template[Template owner]
    Maintainers --> Release[Release manager]

The book is too broad for one reviewer. A credible release needs specialists for hardware, software, security, data, and operations.

Practical rule

The book should model the discipline it teaches: explicit baselines, traceable sources, reviewed changes, tested diagrams, and preserved evidence.