Principles
- Product-first framing: explain user/operator outcome before implementation detail.
- Contract precision: endpoint names, paths, and guarantees must match code.
- Page-one writing: each page should stand on its own.
- Minimal drift: docs are updated in the same PR as behavior changes.
Content Pattern
Recommended section order for major pages:- What this page is for
- Why it matters
- How it works
- Constraints and failure modes
- Related references
Writing Rules
- Prefer plain language over internal shorthand.
- Use tables for contracts and decision tradeoffs.
- State defaults and limits explicitly.
- Avoid aspirational behavior unless marked as roadmap.
- Keep terminology stable across pages.
Change Discipline
For routing/provenance/API contract changes:- update internal docs (
docs/) - update public docs (
mintlify-docs/) - ensure tests/eval checks cover the behavior change