Files
stemengine_old/docs/DOC_GOVERNANCE.md
T
2026-03-18 17:55:21 +09:00

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:

  1. Per PR

    • Author must declare documentation impact in PR template.
    • Reviewer must confirm docs are updated or explicitly not required.
  2. 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:

  1. Confirm documentation-impact PR checks are present in merged changes.
  2. Update user/developer guides for behavior changes.
  3. Update API, troubleshooting, and configuration references as needed.
  4. 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-debt and 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.