Philosophy¶
Ten principles guide every tool, every default, and every generated page.
The Zen of Documentation¶
1. Clarity over cleverness. If a reader has to decode the structure, the structure is already failing.
2. Structure reveals intent. Navigation order is an argument about importance, not just a menu.
3. Primitives are universal — frameworks are dialects. The same 22 canonical primitives recur across stacks; the syntax is what changes.
4. Beauty is functional. Good presentation reduces friction and makes the page easier to trust.
5. One page, one idea. Focused pages are easier to maintain, translate, and validate.
6. Navigation is a contract with the reader. If a page appears in navigation, it should reward the click.
7. Frontmatter is metadata, not decoration. Titles, descriptions, and tags power search, previews, and maintainability.
8. Code examples must run. A broken example erodes trust faster than no example at all.
9. Every admonition earns its place. Callouts are interrupts. Use them when the content truly needs a change in attention.
10. Documentation is a product, not an afterthought. Shipping the feature without the explanation ships only part of the value.
From principle to practice
Read Detect → Profile → Act to see how these principles become tool behavior, then jump to Tools or Quickstart to put them into practice.
What's next¶
-
Why Zen Docs
The product and workflow argument behind the philosophy.
-
Tools
See how the principles map onto the command surface.
-
Quickstart
Go from principles to a working setup in a few minutes.