Docs Authoring And Maintenance

The docs site is a curated publishing surface, not a mirror of every repository note. Good docs changes should help a future reader understand what is stable, where the source of truth lives, and what would make the page stale.

Use Docs Content Model for the publishing boundary and content-class policy. Use this page while doing day-to-day docs work.

Reader Job First

Before creating or moving a page, decide which reader job it serves:

• Admin / Content: Product and CMS concepts for non-platform operators.
• Developer: Architecture, package boundaries, repo workflows, testing, release identity, and docs-site maintenance.
• Operations / Platform: Deployment, runtime configuration, generated artifacts, approval gates, runbooks, and recovery.

Prefer expanding an existing page when the new material supports the same reader job. Create a new page when the topic has its own durable lifecycle, source of truth, or maintenance owner.

Page Lifecycle

Treat docs content as moving through three states:

Working note
  Active thinking, rough checklists, exploratory plans.
  Path: apps/wavemap-docs/working-notes

Curated docs page
  Stable enough to teach from and maintain.
  Path: apps/wavemap-docs/src/content/docs

Generated or reviewed projection
  Produced from deterministic artifacts, then sanitized and reviewed before publication.
  Path: curated docs only after the relevant review gate passes

When roadmap or working-note content becomes stable, promote the durable explanation into the curated docs site and trim the source note back to remaining tasks, open questions, blockers, proof still needed, and links to the durable page.

Placement Rules

Use predictable locations:

Content type	Default location	Notes
Curated admin reference	src/content/docs/admin	Keep operator-facing product language separate from implementation.
Curated developer docs	src/content/docs/developer	Architecture, repo workflow, package, testing, and tooling guidance.
Curated operations docs	src/content/docs/operations	Deployment, cloud, runtime, generated artifacts, and recovery paths.
Public figure assets	src/content/docs/figures	Organize by provenance, not by whichever page first uses the figure.
Active scratch material	apps/wavemap-docs/working-notes	Keep this outside the published docs build.
Raw private evidence	Private workflow outputs, local operator paths, or explicit private artifact directories.	Do not publish directly.

When adding a new curated page, update apps/wavemap-docs/astro.config.mjs so the sidebar exposes it in the correct reader lane.

Figure Assets

Figure folders describe provenance:

Figure class	Public asset path	Source and review model
Generated topology projections	src/content/docs/figures/topology/fig-*.svg	Reviewed generated figure with .mmd sidecar, candidate provenance, and topology figure-slot ledger entry.
Authored conceptual diagrams	src/content/docs/figures/concepts/fig-*.svg	Human-authored teaching diagram with .mmd sidecar and no generated-topology candidate or ledger slot.
Screenshots or bitmap figures	src/content/docs/figures/screenshots/fig-*.<format>	Captured visual evidence; refresh from source instead of hand-editing when possible.

Prefer SVG for diagrams because it stays sharp, small, and readable in diffs. Keep Mermaid source beside Mermaid-derived figures. Use JPG or PNG only when the figure is genuinely photographic, screenshot-based, or raster-first.

Every published figure should have a stable anchor, useful alt text, and a caption that explains provenance:

<a id="fig-short-stable-name"></a>

![Short, specific alt text.](../figures/concepts/fig-short-stable-name.svg)

_Caption. Authored Mermaid source: [fig-short-stable-name.mmd](../figures/concepts/fig-short-stable-name.mmd)._

Do not put authored conceptual diagrams in the topology figure-slot ledger. Reserve that review machinery for generated infra topology projections that come from deterministic topology processing.

Writing Practice

• Start with the reader’s problem, then name the code, command, or artifact that owns the truth.
• Prefer stable concepts and contracts over proof from a single run.
• Link to source-owned contracts, scripts, commands, and durable reference pages instead of copying large blocks.
• Keep operational mutation gates visible near commands that can change infrastructure, permissions, deployments, or data.
• Avoid publishing secret values, account-specific live evidence, raw provider inventory, Pulumi exports, or workflow logs.
• Use explicit dates when documenting time-sensitive decisions.
• Add short “what makes this stale” context when a page depends on a contract, workflow, or cloud shape that is likely to evolve.

Maintenance Checklist

Before finishing a docs change:

• Confirm the page belongs in the right audience lane.
• Add or update sidebar placement for new curated pages.
• Keep raw artifacts and working notes out of the published docs tree.
• Keep figure source sidecars beside rendered figures when applicable.
• Update links from related pages when the new page becomes the durable home for a concept.
• Run the narrowest useful docs check when practical, usually pnpm -C apps/wavemap-docs build.