Explanation¶
Explanation pages are discussion. They step back from the work to give context, background, and reasons: why things are the way they are, what alternatives were considered, and how the parts relate. They support understanding rather than action.
What belongs here
- Design rationale, trade-offs, history, and connections between ideas.
- Opinion and perspective, clearly argued.
- Discussion that a reader could enjoy away from the keyboard.
What does not belong here
- Instructions of any kind → Tutorials or How-to guides
- Lists of facts to look up → Reference
Topics¶
| Topic | Explores | Status |
|---|---|---|
| Specification-driven development | Why every tool is specified to the byte before any code is written | Ready |
| Cross-platform determinism | How identical output on Linux, macOS, and Windows is achieved, and what it costs | Ready |
| Container-first development | Why every task runs in a pinned toolchain container, and how that fits the cross-platform promise | Ready |
| How these docs are organized | The Diátaxis framework and how this site applies it | Ready |
Status: Ready pages are complete. Draft pages describe their planned content and audience.