Project Documentation Structure

Parent: PROGRAMMING_RULES

See also: README/documentation-in-notes — documentation belongs in notes, not .md files in git; repo docs should be single-line pointers to the relevant note.

Rule

Every project gets two parallel subtrees in notes:

<project>/          ← APPLICATION documentation (what the code does)
<project>/dev/      ← DEVELOPMENT PROCESS (how we are building it)

These must be kept strictly separate. Application notes describe the system's design and behaviour; development notes describe the current state of work, decisions made, and how to test.

Application subtree — <project>/

Typical children

<project>/ — index: what it is, architecture overview, links to children
<project>/architecture — major components, layers, boundaries
<project>/data-model (or domain-specific equivalent)
<project>/api — public interfaces
<project>/<feature> — one note per significant feature or subsystem

Rules

Describe the stable design, not work in progress
No phase/status/TODO language here
No test code or test strategy here
Update when the design changes, not when a sprint ends

Development subtree — <project>/dev/

Mandatory children

<project>/dev/ — index
<project>/dev/status — what phases/features are done, in-progress, pending
<project>/dev/decisions — key design decisions with rationale (the why, not just the what)
<project>/dev/testing — test strategy, how to run tests, what each suite covers

Optional

<project>/dev/open-questions — unresolved questions (move to decisions when answered)
<project>/dev/changelog — significant changes per session

Rules

This is working documentation — it should reflect the current reality
status is updated every session; decisions is append-only
testing documents both what is tested and how to run the tests

Note size discipline

Keep individual notes short enough to read in one context window load. If a note is growing large, split it. Prefer more, smaller notes over fewer large ones. Cross-link liberally.