d5ef629a54
Architecture, overview, homelab build plan, agent handbook, ADRs, and agent operating rules. All sensitive operational details sanitized (real IPs, hostnames, client names replaced with generic placeholders). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
78 lines
3.5 KiB
Markdown
78 lines
3.5 KiB
Markdown
# ADR-002: Documentation Structure and Naming Conventions
|
|
|
|
**Status:** Proposed — design agreed, migration pending dedicated session.
|
|
|
|
## Problem
|
|
|
|
The current `docs/` directory is a flat catch-all. Files with no clear taxonomy, inconsistent naming, and no indication of what kind of document they are or what project they belong to. Key symptoms:
|
|
|
|
- `HANDOFF.md` — whose handoff? Only meaningful inside `vps/`
|
|
- Architecture docs, dictation rollout docs, and agent reference docs all live in the same flat directory with no relationship visible from the name alone
|
|
- Dated scratch files mixed with authoritative reference documents
|
|
- No way to know, from a filename alone, what kind of document it is or what project it belongs to
|
|
|
|
This causes agents and operators to either over-read (read everything to find the right document) or under-read (miss relevant documents entirely).
|
|
|
|
## Decision
|
|
|
|
### 1. Adopt Diátaxis as the documentation framework
|
|
|
|
[Diátaxis](https://diataxis.fr) defines four document types, each serving a distinct need:
|
|
|
|
| Type | Purpose | Reader need |
|
|
|---|---|---|
|
|
| **Reference** | Look up a fact | "What is the current state?" |
|
|
| **How-to** | Follow a procedure | "How do I do X?" |
|
|
| **Explanation** | Understand why | "Why is it this way?" |
|
|
| **State** | Track live work | "What is in progress?" |
|
|
|
|
State is not a Diátaxis type but is operationally distinct in a living infrastructure repo — it changes frequently and must be authoritative.
|
|
|
|
### 2. Project-scoped structure
|
|
|
|
Every significant system is a project with its own subdirectory. Project state files are named with their project prefix so they are self-describing without directory context.
|
|
|
|
```
|
|
projects/
|
|
├── vps/
|
|
│ ├── VPS-CURRENT-STATE.md
|
|
│ ├── VPS-HANDOFF.md
|
|
│ └── VPS-PLAN.md
|
|
├── agentlab/
|
|
│ ├── AGENTLAB-CURRENT-STATE.md
|
|
│ └── AGENTLAB-HANDOFF.md
|
|
```
|
|
|
|
### 3. docs/ structure by Diátaxis type
|
|
|
|
```
|
|
docs/
|
|
├── reference/ # Look-up: current facts, inventories, specs
|
|
├── how-to/ # Procedures: step-by-step, operator runbooks
|
|
├── explanation/ # Why: architecture rationale, design context
|
|
├── decisions/ # ADRs: point-in-time architecture decisions
|
|
├── open-loops.md # Active cross-project work tracking
|
|
├── deploys/ # Timestamped deploy logs
|
|
└── archive/ # Historical records
|
|
```
|
|
|
|
### 4. Naming conventions
|
|
|
|
| Rule | Example |
|
|
|---|---|
|
|
| Project state files are prefixed with project name | `VPS-HANDOFF.md` |
|
|
| All filenames are lowercase-hyphenated | `agent-model-reference.md` |
|
|
| ADRs are numbered and describe the decision | `ADR-002-documentation-structure.md` |
|
|
| Service docs match the service name exactly | `prometheus.md`, `loki.md` |
|
|
| Avoid dates in non-archive filenames | ~~`2026-03-25-plan.md`~~ |
|
|
|
|
## Migration rules
|
|
|
|
1. Do not migrate files piecemeal — partial migration breaks the required reading chain
|
|
2. Update all cross-references atomically in the same commit as file moves
|
|
3. Run a grep for every moved filename before committing to catch stale references
|
|
4. Migration is a dedicated session — do not start during active build work
|
|
|
|
## Why not a flat structure
|
|
|
|
A flat `docs/` directory forces readers (human and agent) to scan all files to find the relevant document. Naming cannot communicate type, scope, or authority. The Diátaxis structure makes type and scope visible from the path alone: `docs/how-to/whisperkit-dictation-rollout.md` tells you exactly what it is before you open it.
|