Quantum Platform Documentation Operations

Documentation is an operational control. If users cannot find the approved way to run a workload, they will create unofficial paths. If operators cannot find the current recovery procedure, they will improvise under stress. If reviewers cannot find the evidence policy, claims will be evaluated inconsistently.

Backstage TechDocs supports a docs-like-code model in which technical documentation is associated with cataloged services and written in Markdown-style source [R212]. A quantum platform should use the same pattern: documentation lives near the system it describes, is reviewed like code, and is surfaced through the service catalog.

flowchart LR
    Source[Docs source] --> Review[Pull request review]
    Review --> Build[Static build]
    Build --> Portal[Developer portal]
    Portal --> Catalog[Service catalog]
    Catalog --> Users[Users and operators]

Documentation classes

flowchart TB
    Docs[Quantum documentation] --> Concept[Concept docs]
    Docs --> HowTo[How-to guides]
    Docs --> Reference[Reference docs]
    Docs --> Runbooks[Runbooks]
    Docs --> Policy[Policy docs]
    Docs --> Evidence[Evidence templates]

Each class has a different owner and review standard. A concept page can tolerate narrative style. A runbook must be executable. A policy page must be authoritative and versioned.

Documentation ownership

flowchart TB
    Doc[Document] --> Owner[Owner]
    Doc --> Reviewer[Technical reviewer]
    Doc --> Approver[Policy approver]
    Doc --> Expiry[Review-by date]
    Doc --> System[Related catalog entity]

Every operational page should include an owner and review-by date. Stale documentation is a failure mode, not a cosmetic issue.

Docs and incidents

sequenceDiagram
    participant Incident as Incident commander
    participant Portal as Docs portal
    participant Runbook as Runbook
    participant Evidence as Evidence store
    Incident->>Portal: Search affected service
    Portal->>Runbook: Open current recovery runbook
    Runbook->>Incident: Preconditions and safe actions
    Incident->>Evidence: Record action and doc version

The incident record should include which runbook version was followed. If the runbook was wrong, update it as part of the post-incident action list.

Documentation tests

Docs can be tested.

flowchart LR
    DocsPR[Docs pull request] --> Links[Link check]
    DocsPR --> Mermaid[Mermaid render check]
    DocsPR --> Snippets[Code snippet test]
    DocsPR --> Policy[Policy metadata check]
    DocsPR --> Owners[Owner check]
    Owners --> Merge{Merge allowed?}

For this book and for platform docs, Mermaid diagrams should be treated as build artifacts. Broken diagrams erode trust because the reader cannot distinguish a rendering error from a conceptual error.

Documentation release cadence

stateDiagram-v2
    [*] --> Draft
    Draft --> Reviewed
    Reviewed --> Published
    Published --> NeedsReview: review date reached
    Published --> Deprecated: service retired
    NeedsReview --> Reviewed
    Deprecated --> Archived

High-change docs such as backend availability pages may update continuously. Policy docs should change through explicit review. Runbooks should change after drills, incidents, or platform releases.

Quantum-specific documentation gaps

flowchart TB
    Gaps[Common gaps] --> Baseline[No baseline explanation]
    Gaps --> Mitigation[Mitigation settings undocumented]
    Gaps --> Cost[Cost envelope unclear]
    Gaps --> Claims[Claim criteria vague]
    Gaps --> Failure[Failure modes missing]
    Gaps --> Ownership[No owner or support path]

The most frequent documentation failure is not missing theory. It is missing operational constraint: when to use the service, when not to use it, what evidence it produces, and whom to contact when it fails.

Practical rule

Documentation is production infrastructure when it changes operator behavior. Treat it as code, connect it to the catalog, test it in CI, and update it after every meaningful operational lesson.