Skip to main content

​
Documentation Architecture

These docs serve multiple audiences across a complex protocol ecosystem. Here’s how the entire documentation site is organized:
SectionContents
CoW ProtocolOverview, Explanation (How It Works, Benefits, Order Types, Flash Loans, CoW AMM, Architecture), CoW Swap (Trading Tutorials, Widget, Hook dApps), CoW Explorer, Integration (API, Quickstarts, Testing), Reference (APIs, Core, Auctions)
Developer SDKsTypeScript SDK, Python SDK
ContractsCore Contracts, Hooks Trampoline, ComposableCoW, Contracts SDK, Flash Loan Router
InfrastructureBFF, Services, Watch Tower
GovernanceMission & Token, Grants, Fees

​
Framework: Diataxis

Every section follows the Diataxis framework, which organizes content into four quadrants based on what readers need:
LearningWorking
PracticalTutorials — Step-by-step lessonsHow-To Guides — Task-oriented guides
TheoreticalExplanation — Concepts and contextReference — Technical specifications

​
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:
PersonaEntry PointPrimary Sections
TraderCoW Swap tutorialsOrder types, CoW Swap, CoW Explorer
IntegratorIntegration overviewWidget, SDK, API, quickstarts
Solver OperatorTest a solver locallySolver tutorials, auction reference
Smart Contract DevContracts referenceComposableCoW, Hooks, Flash Loans
Backend ContributorServicesBFF, Services, Watch Tower
DAO ParticipantGovernanceGrants, fees, voting
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

GapWhat’s neededPriority
Flash loan SDK guideProgrammatic flash loan order creation via SDK. The current tutorial is UI-focused with a Sepolia walkthrough but lacks an SDK-first guide.Low
Batch order creationHow to create and manage multiple orders in a single session — useful for market makers and automated strategies.Low

​
Structural weaknesses

AreaIssue
Multi-chain specificsDocs are Ethereum-centric. Gnosis Chain, Arbitrum, and Base have different liquidity profiles, gas dynamics, and solver participation, but chain-specific guidance is sparse.
Code freshnessStatic code snippets can go stale as the SDK evolves. The interactive tutorials at learn.cow.fi mitigate this, but in-docs examples need periodic review against latest SDK versions.
API reference depthThe Orderbook API reference links to the external api.cow.fi/docs for full specs. Inline parameter documentation within the docs would reduce context-switching.
Solver docsThe solver tutorials cover creation and deployment, but advanced topics (custom routing strategies, gas optimization, competition dynamics) are thin.

​
How to help

If you’d like to contribute to any of these areas:
  1. Check the GitHub repository for the docs source
  2. Follow the Diataxis framework to decide where content belongs
  3. Use existing guides as templates for style and structure
  4. Ask in Discord #tech-talk if you need protocol-level clarification

​
Tech Stack

ComponentTool
Documentation platformMintlify (Sequoia theme)
Content formatMDX (Markdown + JSX components)
DiagramsMermaid (rendered by Mintlify)
API docsOpenAPI specs (auto-rendered)
Version controlGit (GitHub)
AI integrationMintlify native (Claude, ChatGPT, Perplexity, Cursor, MCP)
SearchMintlify built-in search

​
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

ComponentWhen to use
<Steps> / <Step>Sequential procedures (quickstarts, tutorials)
<CardGroup> / <Card>Navigation grids, feature showcases
<Accordion>Expandable details, FAQ items
<Note>Supplementary information
<Warning>Common mistakes, breaking changes
<Tabs> / <Tab>Language-specific code (TypeScript vs Python)
<CodeGroup>Multiple code examples side by side
Mermaid code blocksArchitecture diagrams, flowcharts

​
File naming conventions

section/
├── explanation/          # Conceptual content ("why")
│   ├── topic-name.mdx
├── tutorials/            # Step-by-step lessons
│   ├── task-name.mdx
├── howto/                # Task-oriented guides
│   ├── task-name.mdx
└── reference/            # Technical specs
    ├── topic-name.mdx
All navigation is configured in docs.json at the project root. Each tab has groups, and groups contain pages. The structure: 
{
  "navigation": {
    "tabs": [
      {
        "tab": "Tab Name",
        "icon": "icon-name",
        "groups": [
          {
            "group": "Group Name",
            "icon": "icon-name",
            "pages": ["path/to/page"]
          }
        ]
      }
    ]
  }
}

​
Keeping Docs Current

​
When protocol changes land

  1. API changes — Update the OpenAPI spec, then update any quickstarts or guides that reference affected endpoints
  2. New features — Add explanation page (what/why), tutorial (how to use), and reference (specs)
  3. Contract deployments — Update snippets/core-contract-addresses.mdx and 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 in snippets/ and is imported via MDX:
SnippetContent
community-links.mdxDiscord, GitHub, Forum, Snapshot cards
core-contract-addresses.mdxSettlement contract addresses per chain
supported-networks.mdxSupported blockchain networks
sdk-install.mdxSDK installation command
settlement-contract.mdxSettlement contract reference
Last modified on March 12, 2026