Documentation Standard
Documentation Standard
Section titled “Documentation Standard”Canonical Location
Section titled “Canonical Location”Durable, human-authored documentation lives under docs/src/content/docs/. Service-local README files may contain setup notes and pointers, but canonical explanations belong in this docs site.
Page Metadata
Section titled “Page Metadata”Every canonical human-authored page must include frontmatter with these fields:
- title
- status
- owner
- domains
- doc_type
- last_reviewed
- related_code
Use related_docs when a page depends on an ADR, standard, flow, generated reference, or another canonical page.
Status Values
Section titled “Status Values”Normal documentation status values:
- draft
- active
- needs-review
- deprecated
ADR status values:
- proposed
- accepted
- superseded
Document Types
Section titled “Document Types”Supported doc_type values:
- overview
- architecture
- service
- flow
- adr
- standard
- operation
- runbook
- generated-index
Source Linking
Section titled “Source Linking”Every durable factual claim should link to source code, configuration, generated references, an ADR, or another canonical page where practical. Use related_code for the authoritative code paths and inline links for the exact evidence readers need.
Diagrams
Section titled “Diagrams”Use Mermaid for diagrams by default. The docs site renders Mermaid fences through astro-mermaid, and GitHub renders them in the file view. Use checked-in SVG or PNG assets when Mermaid cannot express the diagram clearly.
Use Starlight callouts (:::note, :::tip, :::caution, :::danger) for a caveat the reader must not miss. See the Rich Formatting Standard for choosing a format, writing diagrams people can read, and when a page may use MDX or a standalone HTML artifact.
Shared assets live under docs/src/content/docs/_assets/ or docs/public/assets/ depending on whether the asset is content-specific or globally served.
Page-specific assets live beside the page in an _assets/ folder.
Generated References
Section titled “Generated References”Generated docs stay in the paths where generation tools write them. Canonical docs should index generated references and explain how to regenerate them. Do not hand-edit generated docs.
Service-Local Docs
Section titled “Service-Local Docs”After migration, service-local docs should point to canonical docs. They should not duplicate architecture, flows, standards, or decisions.
Deployment And Secrets
Section titled “Deployment And Secrets”The internal docs site is built from docs/ and deployed behind Cloudflare Access. Do not put secrets, live DSNs, bearer tokens, or credentials in docs.