docker/docs/documentation-strategy.md

Documentation Strategy

This repository's documentation should help both humans and Codex agents make safe, accurate changes.

Principles

1. Authority first: identify authoritative files clearly (Compose + services-up.sh for runtime; Terraform for structured inventory/reconciliation).
2. Task-oriented docs: include practical workflow steps, not only conceptual text.
3. No speculation: document implemented behavior, not aspirational designs without code evidence.
4. Cross-linking: root README and topic docs should point to each other for discoverability.
5. Safety clarity: explicitly note what should not be committed or applied casually.

Documentation quality checklist

Before merging doc changes, check:

• Is this statement verifiable from current repo files?
• Does this conflict with existing docs?
• Does this clarify source-of-truth boundaries?
• Does this improve a real workflow for contributors/Codex?
• Are sensitive details excluded?

Recommended update cadence

Update docs when any of these change:

• services-up.sh composition behavior,
• major Compose directory or profile structure,
• Terraform workflow conventions,
• inventory output shapes,
• secret handling conventions.

Audience-specific outcomes

• Humans should quickly understand how to operate the repo safely.
• Future Codex runs should quickly identify authoritative files, guardrails, and reconciliation workflows.