audita/docs/documentation/policy.md

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.