Documentation Maintenance

This page defines how contributors keep the site consistent and how a future, owner-approved Dosu pilot could propose repository documentation updates. No Dosu account, source, monitor, repository permission, or document was changed for this guidance.

Page placement and stable paths

Put shared onboarding and architecture in their existing onboarding or platform sections, end-to-end journeys in content/flows/, system-specific pages under the owning project's stable slug, and shared references or runbooks in their existing sections. Reuse the canonical page before creating a duplicate. Keep published paths stable; when a move is necessary, update incoming links and preserve a working compatibility path where supported.

Keep reusable Markdown starters in templates/. Keep plans, task briefs, migration records, and implementation artifacts outside content/; they are not reader-facing pages and must stay out of site navigation and search.

Metadata and evidence

New and substantially rewritten pages use these editorial frontmatter fields:

owner_system: documentation
evidence_status: unknown
source_refs: []

Use owner_system for the responsible system. evidence_status must be exactly one of:

Value	Use
source-verified	Material technical claims were checked against the cited source revision.
documented	Claims come from existing documentation and have not been directly checked in source.
partial	Some material claims or flow segments remain unverified.
unknown	Evidence is unavailable or insufficient to characterize the behavior.
legacy	Historical material is preserved and is not represented as current behavior.

source_refs is an array of { repository, commit, path } objects. Record the real repository identifier, full commit SHA, and repository-relative source path. Use an empty array when no repository source has been verified. Never invent a revision, use a branch name as a revision, or imply that a citation proves claims beyond its source. Cite external references inline in the prose when needed; do not disguise a URL as a repository source reference.

Set reviewed_at only after the page's evidence has actually been reviewed, and record that real date. Evidence review may be agent-led or human-led; record reviewer identity and type with the evidence or review record when useful. A template, generation run, or successful build alone is not an evidence review. This date does not signal human or owner acceptance; human review of the rendered result is a separate step. If evidence is mixed, state which sections are verified and keep the overall status honest. Attribute each behavior to the component that implements it, and label assumptions, proposals, and historical descriptions.

Contributor review sequence

Edit the source Markdown, validate claims and links against evidence, run npm run build, run npm run docs:check, then request human review of the rendered result. The repository-root CONTRIBUTING.md and documentation workflow are the working entry points.

Operational commands

Production commands require explicit approval for each exact command and target, including read-only diagnostics. Before an approved command is run, state the command and target. Approval for one command does not authorize another. Mark production diagnostics and recovery commands as approval-bound in runbooks. Documentation generation and review must never execute commands copied from documentation.

Future Dosu import and sync pilot

Dosu's published Self-Documenting PRs guidance says accepted changes to imported repository documents are sent back through a sync pull request when Auto-Accept Review is off. That describes the product behavior; the cross-repository flow for this documentation site remains unverified until the pilot below succeeds.

Treat this as a future proposal, not an active integration. Before configuration, the owner must approve the exact source repository, documentation repository, documents to import, and monitored paths. Import only the canonical reader-facing Markdown intended for sync. For the code source, monitor only the owner-approved source directories that map to the pilot document; do not rely on the default whole-repository scope. Determine and record the exact paths from source mapping before enabling anything. Exclude unrelated repositories and paths, generated output, credentials, and private operational data. Keep Auto-Accept Review off so a person can inspect the proposed change and the docs sync PR before it is merged.

The pilot passes only when one owner-approved code PR affecting a mapped source path produces a correctly scoped documentation suggestion, a sync PR in this docs repository with accurate evidence and metadata, a human-reviewed change, and a passing site build. Record the observed repositories, paths, PR links, review outcome, and build result in the pilot evidence. Until that end-to-end test runs, cross-repository behavior is unverified and no monitoring or permissions should be assumed active.