Documentation Architecture
These docs serve multiple audiences across a complex protocol ecosystem. Here’s how the entire documentation site is organized:Framework: Diataxis
Every section follows the Diataxis framework, which organizes content into four quadrants based on what readers need:How to decide where content belongs
Quick rules
- Tutorials teach. They have a learning outcome. “By the end, you’ll have placed your first swap.”
- How-to guides accomplish. They solve a task. “How to integrate the widget into your app.”
- Explanation clarifies. It provides context. “Why CoW Protocol uses batch auctions.”
- Reference describes. It’s precise and complete. “The /quote endpoint accepts these parameters.”
Personas
The docs serve distinct audiences with tailored entry points:
Each persona has a clear path from the home page — the “Find Your Path” table provides direct links.
Sitemap
Tab Structure
CoW Protocol Tab (detailed)
Known Gaps
These are areas where the documentation is incomplete or could be significantly improved. Contributions are welcome — see Content Guidelines below for how to structure new pages.Missing guides and tutorials
Structural weaknesses
How to help
If you’d like to contribute to any of these areas:- Check the GitHub repository for the docs source
- Follow the Diataxis framework to decide where content belongs
- Use existing guides as templates for style and structure
- Ask in Discord #tech-talk if you need protocol-level clarification
Tech Stack
Content Guidelines
Writing style
- Direct and concise — lead with the answer, not the reasoning
- Code-first — show, don’t tell. Every concept should have a code example
- Multi-language — TypeScript + Python + cURL where applicable
- Practical — every page should help someone do something
Mintlify components we use
File naming conventions
Navigation (docs.json)
All navigation is configured indocs.json at the project root. Each tab has groups, and groups contain pages. The structure:
Keeping Docs Current
When protocol changes land
- API changes — Update the OpenAPI spec, then update any quickstarts or guides that reference affected endpoints
- New features — Add explanation page (what/why), tutorial (how to use), and reference (specs)
- Contract deployments — Update
snippets/core-contract-addresses.mdxand any per-chain address tables
Cross-references
The docs use extensive internal linking. When adding new pages:- Link from relevant existing pages
- Add to the “Next Steps” section of related pages
- Update the home page if it’s a major new section
- Add to the appropriate navigation group in
docs.json
Reusable snippets
Common content lives insnippets/ and is imported via MDX: