Documentation Guidelines
Don’t Document What Tooling Enforces
Section titled “Don’t Document What Tooling Enforces”- TypeScript enforces types → don’t duplicate type info in prose
- ESLint enforces style → don’t document code style rules
- Tests document behavior → don’t duplicate test cases in docs
Do Document
Section titled “Do Document”Architecture Decisions (ADRs)
Section titled “Architecture Decisions (ADRs)”When making significant technical decisions, create an ADR:
apps/handbook/src/content/docs/architecture/decisions/ADR format:
- Status (proposed, accepted, deprecated)
- Context (why this decision was needed)
- Decision (what was decided)
- Consequences (trade-offs, risks)
Data Sources and Constraints
Section titled “Data Sources and Constraints”Document API quirks, rate limits, and gotchas in Data Sources.
Scientific Context
Section titled “Scientific Context”Add astronomy terms to the Glossary. Assume readers know programming but may not know cosmology.
Getting Started
Section titled “Getting Started”Onboarding steps that aren’t obvious from the code itself.
Non-Obvious Trade-offs
Section titled “Non-Obvious Trade-offs”When code looks wrong but is intentional, document why.
Where to Document
Section titled “Where to Document”| What | Where |
|---|---|
| API behavior | TypeScript types + JSDoc |
| Architecture decisions | ADRs |
| Data source details | Data Sources page |
| Scientific terms | Glossary |
| Package purpose | Package-specific page |
| App features | App-specific page |
Writing Style
Section titled “Writing Style”- Be concise
- Use present tense
- Show, don’t tell (code examples > prose)
- Keep code blocks minimal
- Link to external docs rather than duplicating