Documentation Workflow

Update documentation when a code or operational change affects onboarding, architecture, integrations, scheduled work, runbooks, deployment, or system boundaries. The repository's contributor guide defines the review sequence; this page explains how to choose a page and assess its evidence.

Keep documentation close to the project owner section:

• Shared concepts go under content/platform/ or content/onboarding/.
• Cross-system business journeys go under content/flows/.
• System-specific material goes under content/projects/<stable-project-slug>/, using the closest existing section.
• Shared references and runbooks go under content/reference/ and content/runbooks/.

Keep established paths stable. Extend the existing canonical page when possible. When a page must move, update its incoming links and preserve a working compatibility path where supported. Reusable templates live in templates/; plans and migration artifacts stay outside content/ so they are not published as site pages.

Evidence and metadata

Every new or substantially rewritten page uses these frontmatter fields:

• owner_system: the system responsible for the page.
• evidence_status: exactly source-verified, documented, partial, unknown, or legacy.
• source_refs: an array of { repository, commit, path } records using a real repository identifier, full source commit, and repository-relative path. Use [] when no repository source has been verified.
• reviewed_at: add only after the page's evidence has actually been reviewed; use the actual date. Record reviewer identity and type with the evidence or review record when useful. This date does not signal human or owner acceptance.

Use source-verified only for material claims checked against the cited source. Use documented for claims supported by existing documentation without a direct source check, partial when material paths or claims remain unresolved, unknown when evidence is unavailable, and legacy for preserved historical material. Link each technical claim to evidence where possible. Distinguish implementation facts from assumptions, historical behavior, and proposals. State gaps beside the affected content; never fill a gap with an invented connection.

Document an interface from source

Use templates/interface.md when documenting a screen or menu entry. Trace the visible action through its route parameters, controller, template/component, service and any asynchronous or external effect. The Logidav menu inventory and Meduse interface map show this structure. Reused endpoints should link to a shared workflow while retaining account, channel, tenant and source differences.

When source changes, update the relevant route inventory and workflow together. Compare added/removed routes, changed request fields, processor destinations and schedules; preserve stable page paths and replace source pins only after checking the new revision. This gives a future documentation agent a bounded source-to-page mapping; it does not enable Dosu monitoring.

Contributor sequence

Use the same ordered workflow for each change:

1. Edit the Markdown source at its stable path.
2. Validate evidence, metadata, and links. Record unresolved gaps honestly.
3. Run npm run build from the repository root.
4. Run npm run docs:check from the repository root.
5. Ask for human review of the rendered page, source attribution, evidence status, and operational safety.

Templates are scaffolds, not evidence. Do not copy a sample commit or review date. A production command shown in documentation—including a read-only diagnostic—remains approval-bound for each exact command and target. Generating or reviewing documentation does not authorize or execute it.

For evidence definitions, stable-path rules, and the future Dosu sync pilot, see Documentation maintenance.