Axıs
随笔
技能目录

Documentation Governance

Documentation Governance

Purpose

Documentation should reduce uncertainty, not create another information system that competes with the project itself.

Adapt to the project, but distinguish among:

  • onboarding / overview
  • architecture
  • decisions
  • requirements or specification
  • plans / roadmap
  • operational instructions
  • research / notes
  • release information
  • archive

Do not create every category automatically.

Source of Truth

Choose one authoritative location for each major fact.

Typical examples:

  • version → Git tag/release or version authority
  • current state → project-status document
  • architecture → architecture document
  • decisions → decision record
  • roadmap → project planning source

If multiple documents duplicate the same fact, either make one authoritative or remove the duplication.

Lifecycle

Use lifecycle states appropriate to the project:

DRAFT → ACTIVE → STABLE → DEPRECATED → ARCHIVED

Not every document needs every state.

A deprecated document should make its successor or reason for retention clear when practical.

Naming

Use names that reflect function rather than vague sequence:

Prefer:

  • ARCHITECTURE.md
  • PROJECT_STATUS.md
  • DECISIONS.md
  • ROADMAP.md

Avoid:

  • notes-final.md
  • new-plan.md
  • old-architecture.md
  • read-this-one.md

unless the lifecycle context genuinely requires such naming.

Indexing

Large documentation systems benefit from a small index or entry document.

The index should identify:

  • what to read first
  • authoritative documents
  • deprecated material
  • major project areas

Do not duplicate the contents of those documents in the index.

Completion Rule

When implementation changes materially affect documented behavior, check whether the relevant documentation must change before declaring the work complete.