Skip to content
Rymflux Documentation
Esc
↑↓navigate↵open⌘Jpreview
On this page

Scaffold documentation governance

Scaffold documentation governance

How to treat files under docs/ after you copy this scaffold into your repository.

File classes

Class What it is What you do
Structural README README.md in a folder describing purpose, audience, owner, phase Keep. Update owners/paths to match your org. Do not delete unless you remove the whole folder.
Replace-me stub Thin starter content (e.g. charter vision.md) marked Draft Replace with real content using the mapped upstream template (see KIT.md).
Example stub example-*.md with placeholder fields (e.g. example-runbook.md) Replace or delete when your own content goes in that folder.
Template copy Files you create from the upstream templates/ kit Add when the phase starts; do not invent a parallel structure.
Placeholder (.gitkeep) Keeps empty dirs in Git Keep until the first real file arrives; then delete .gitkeep.
Generated / CI artifacts e.g. coverage reports Publish from CI or link out; do not hand-maintain forever.

Reference policy

Copied docs/ files must only use in-repo relative links (paths that exist in this product repository).

Teaching chapters, templates, examples, and the first-week pack live in the upstream Docs-as-Code Primer kit. They are listed in KIT.md — not linked via ../primer/... (those paths break after copy).

Stub policy

  1. Folder README.md files are structural, not product examples. They answer “what belongs here?”
  2. They are not required reading after onboarding — follow the upstream FIRST_WEEK.md (see KIT.md).
  3. Do not pre-fill every folder with fictional product prose in the scaffold. Filled samples live upstream under examples/acme-export-platform/.
  4. Select folders include example stubs (example-*.md) — thin placeholder files with fields you fill in. These are a starting point, not real content. Replace or delete them when you add your own files.
  5. If a structural README feels noisy, you may shorten it — but keep purpose + stream + a pointer to KIT.md / this file.

Charter stubs

Split files under internal/charter/ map 1:1 to sections of upstream templates/vision-charter.md. Mapping table: upstream appendix/phase-folder-map.md (see KIT.md).

Stub file Upstream template section
vision.md Vision statement + KPIs
scope.md Scope
stakeholders.md Stakeholders & RACI
constraints-assumptions.md Constraints + Assumptions
risk-register.md Initial risk register

When you reorganize

  1. Keep an in-repo note of your phase → folder map (optional: vendor appendix/phase-folder-map.md into this repo).
  2. Update AGENTS.md (repo root) source-of-truth table.
  3. Prefer redirects or “moved to” notes over silent deletes for the first release cycle.

Adding a new doc type

  1. Decide stream: internal / user / shared (upstream primer/14-content-governance.md — see KIT.md).
  2. Place under the phase folder from the canonical map.
  3. Add or extend a template if the shape will repeat.
  4. Link in-repo resources from the folder README; list upstream template names via KIT.md.

Versioning policy

Documentation is versioned with the code it describes. Until the first shipped app release we publish a single “latest” site from main — every change is a commit, so history is preserved and nothing needs to be frozen yet.

  1. Live site = main. main is the source of truth; the deploy pipeline publishes it to Cloudflare Pages. No long-lived doc branches for now.
  2. Tag in lockstep with app releases. When the application cuts a release (vX.Y.Z), tag the docs repo at the matching commit (git tag v0.2.0 && git push origin v0.2.0). The tag is the frozen doc snapshot for that app release — git checkout v0.2.0 reproduces exactly what was published.
  3. Changelog every release. Add a type: changelog entry under user/changelog/ for each released version (what changed, migrated, deprecated). Blume renders the /changelog timeline and /changelog/rss.xml feed automatically. See user/changelog/README.md.
  4. Rollback = re-promote a Pages deployment. Every deploy has a stable hash URL; use the Cloudflare dashboard to roll back rather than reverting git.
  5. Adopt versioned docs only when needed. When two or more released app versions need different docs, enable Blume’s version selector (navigation.selectors with contextKind: "version") and keep a docs branch per released series. Before that, it is overhead.

The end-to-end steps live in the Release and deploy runbook.

Was this page helpful?