28 lines
1.3 KiB
Markdown
28 lines
1.3 KiB
Markdown
# Documentation Policy
|
|
|
|
## Scope
|
|
This policy defines how project documentation should be authored and maintained.
|
|
|
|
## Core rules
|
|
- Document the current behavior of the codebase.
|
|
- Remove stale behavior descriptions promptly when code changes.
|
|
- Do not describe development history in architecture or behavior docs unless a document is explicitly historical.
|
|
- Do not use architecture or behavior docs as changelogs.
|
|
- Prefer rewriting stale sections from scratch when substantial behavior or ownership changes occur.
|
|
|
|
## Consistency requirements
|
|
- Keep command examples aligned with current CLI surfaces.
|
|
- Keep configuration examples aligned with supported fields and precedence.
|
|
- Keep architecture package ownership descriptions aligned with current code layout.
|
|
- Keep stable contract identifiers accurate (module keys, validator keys, output-schema keys, report metadata fields).
|
|
|
|
## Cross-document expectations
|
|
- `docs/architecture/*` documents runtime behavior and package ownership.
|
|
- `docs/configuration.md` documents config schema and precedence.
|
|
- `docs/development.md` documents contributor workflow and engineering conventions.
|
|
|
|
## Review expectations for documentation changes
|
|
- Verify referenced files and links exist.
|
|
- Verify examples match current behavior.
|
|
- Prefer concise, direct language and avoid speculative future claims.
|