50 lines
1.6 KiB
Markdown
50 lines
1.6 KiB
Markdown
# Documentation Policy
|
|
|
|
## Three trees + agent
|
|
|
|
| Tree | Audience | Freshness rule |
|
|
|------|----------|----------------|
|
|
| `living_docs/` | Everyone — **current truth** | Update every significant session |
|
|
| `developer_docs/` | Contributors | Update with technical changes |
|
|
| `user_docs/` | End users | Update with user-visible changes |
|
|
| `agent/` | Humans + AI process | Update when process/rules change |
|
|
|
|
## living_docs/
|
|
|
|
| File | When to update |
|
|
|------|----------------|
|
|
| `ROADMAP.md` | Phase status, acceptance, owners |
|
|
| `PROGRESS.md` | Append-only each session with real work |
|
|
| `CURRENT_STATUS.md` | After any “what works” change |
|
|
| `ARCHITECTURE_OVERVIEW.md` | Design changes |
|
|
| `OPEN_QUESTIONS.md` | New/resolved questions |
|
|
| `CHANGELOG.md` | User-visible or notable internal changes |
|
|
|
|
## developer_docs/
|
|
|
|
Update the matching file when you touch that domain (setup, architecture, modules, protocol, build, testing).
|
|
|
|
## user_docs/
|
|
|
|
- Ship accurate instructions only for **implemented** features.
|
|
- Label incomplete features **Planned** with phase.
|
|
- Never claim multiplayer works until Phase 2 acceptance is met.
|
|
|
|
## ADRs
|
|
|
|
- Required before architecture/protocol/security merges.
|
|
- Status lifecycle: Proposed → Accepted → (Deprecated|Superseded).
|
|
- Linking: ROADMAP and ARCHITECTURE should cite ADR numbers.
|
|
|
|
## Same-change rule
|
|
|
|
Documentation updates belong in the **same PR/commit** as the code they describe. “Docs follow-up later” is not complete work.
|
|
|
|
## End of session checklist
|
|
|
|
1. `PROGRESS.md` entry
|
|
2. `CURRENT_STATUS.md` if reality changed
|
|
3. `CHANGELOG.md` if notable
|
|
4. Specialist docs for the area touched
|
|
5. ADR if decision changed
|