beatz174-bit
37 lines
1.4 KiB
Markdown
37 lines
1.4 KiB
Markdown
# 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.
|