Documentation Standard
Documentation rules — pointers over duplication, live commands over static tables
Tags
Overview
Purpose
Documentation rules — pointers over duplication, live commands over static tables
Rules
DOC-001: Document WHERE to look, not HOW it works. Code is the source of truth.
How-it-works documentation rots the moment code changes. Where-to-look pointers remain valid across refactors.
Verification: Doc review: documentation provides file paths and command references, not implementation descriptions.
DOC-002: Static documentation of implementation becomes stale immediately. Use commands instead.
A command like 'sbx describe' always returns current state. A static table is wrong the moment someone changes a file.
Verification: Doc review: runnable commands preferred over static tables for discoverable information.
DOC-003: README files should point to schemas/scripts, not duplicate their content.
Duplicated content creates two sources of truth. When the schema changes, the README becomes a lie.
Verification: Doc review: README references point to authoritative files, not inline copies.
DOC-004: Replace static file trees with ls commands. Replace status tables with git log.
Dynamic discovery commands produce accurate output at read time. Static file trees are outdated on the next commit.
Verification: Doc review: discoverable information uses commands over static representations.
DOC-005: Never maintain same information in two places. One source, pointers everywhere else.
Duplicate information guarantees inconsistency. The only question is when, not if, the copies will diverge.
Verification: Doc review: grep for duplicated definitions. Each fact has exactly one authoritative source.