SDK Documentation Best Practices (Vocs)

Rules for writing clear, scannable, code-forward documentation for public SDKs, targeting Vocs as the documentation framework. Derived from analysis of best-in-class SDK documentation (wagmi, viem, TanStack). Rules are domain-agnostic; examples use generic SDK patterns with occasional web3 illustrations.

Two Audiences, One Source

Vocs ships every page twice: rendered HTML for humans, raw Markdown for agents (.md routes, llms.txt, llms-full.txt, MCP). You do not write two versions — you write Markdown that is good enough to survive both surfaces. Everything below serves that goal, and it changes three habits: