Documentation conventions
Source responsibilities
- Beads stores workflow state, dependencies, priorities, claims, findings, and execution evidence.
- Feature
design.mdfiles store intended feature behavior and design decisions. - Reader-facing pages under
docs/src/describe current supported behavior. - Implemented-feature
index.mdfiles preserve feature-specific delivery and audit history. planned-features.mdprovides a human roadmap; Beads is authoritative for live execution state.- Code and tests provide implementation evidence.
Page placement
Choose a page by the question the reader is asking:
| Reader question | Documentation concern |
|---|---|
| What is this project, who is it for, and what does it currently promise? | Introduction |
| Why is it structured this way, and what boundaries or invariants apply? | Architecture |
| How do I use, deploy, configure, observe, operate, or recover it? | Operator’s Manual |
| How do I build, test, change, migrate, or extend it? | Development Guide |
| What is the exact command, configuration key, interface, field, schema, default, or contract? | Reference |
| What did one delivered feature change, and how was it verified? | Implemented Features |
Create focused project-specific pages when a durable reader question exists. Do not create empty pages merely to fill a category. A project may rename or omit a concern when it genuinely does not apply, but navigation, feature designs, and validation rules must be updated together.
Feature documentation
A feature design must name exact existing pages to update and exact new pages to create. Section names alone are not sufficient. User-facing documentation must stand on its own; readers should not need the internal feature design to understand supported behavior.
Status language
- Planned: intended but not delivered.
- Implemented: present in code but not necessarily validated or fully documented.
- Supported: implemented, validated, documented, and part of the current contract.
- Deprecated: still present but scheduled for replacement or removal.
- Removed: no longer available.
Drift handling
When design, implementation, tests, Beads, or published docs disagree:
- record the mismatch in Beads;
- determine whether the divergence was intentional;
- correct the implementation or update the appropriate authoritative artifact;
- preserve the rationale and validation evidence;
- close the drift issue only after the sources agree.
Writing style
State current behavior directly. Separate planned behavior from delivered behavior. Prefer exact commands, paths, defaults, failure cases, and validation evidence where precision matters.