2.2 KiB
2.2 KiB
Documentation Governance (Phase 3)
This document defines how documentation stays fresh as StemEngine evolves.
1) Policy
- Documentation updates are required for meaningful behavior changes.
- Documentation review is part of pull request completion.
- Release readiness includes documentation verification.
2) Cadence
Two cadences are enforced:
-
Per PR
- Author must declare documentation impact in PR template.
- Reviewer must confirm docs are updated or explicitly not required.
-
Per release / monthly review
- Run a docs freshness pass at each release.
- If releases are infrequent, run at least once per month.
3) Owner rotation
Use a rotating documentation steward role.
- Rotation period: one release cycle (or one month)
- Owner: assigned in planning/release issue
- Backup owner: one additional maintainer
Steward responsibilities:
- Validate docs are linked and discoverable.
- Verify API docs reflect current endpoints.
- Verify troubleshooting and config references are still accurate.
- Track stale or missing docs as follow-up work.
4) PR requirements
Every PR must answer documentation impact via template:
- docs updated, or
- docs explicitly not needed with rationale.
Common triggers requiring docs update:
- New/changed endpoint or request shape
- New/changed environment variable
- Feature behavior changes visible to users
- New sidecar/runtime dependency
- New operational or troubleshooting behavior
5) Release checklist integration
Before tagging a release:
- Confirm documentation-impact PR checks are present in merged changes.
- Update user/developer guides for behavior changes.
- Update API, troubleshooting, and configuration references as needed.
- Add migration note when compatibility or operations changed.
6) Escalation for stale docs
If docs drift is found:
- Open a documentation debt issue in the same milestone.
- Label as
docs-debtand include impacted files. - Assign to current documentation steward.
7) Definition of healthy docs process
The process is healthy when:
- PRs consistently declare documentation impact.
- Release checks catch stale docs before release.
- New contributors can ship changes without tribal knowledge.