vocs-documentation

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:

• Structure is machine-readable. Task-based headings, one topic per page, and a real

description are what a retriever matches on. A page called "Overview" with three unrelated sections is worse in llms.txt than three focused pages.

• Prose density is a token cost. Padding that a human skims past is context an agent spends

budget on. Terse fragments beat full sentences in reference material.

• Interactive components must degrade. Any custom MDX component in a page needs a toMarkdown

hook, or it reaches agents as an opaque JSX tag. Run vocs markdown-audit to catch these.

See references/agent-readable-docs.md for the mechanics.

Documentation Type Router

The four types come from Diátaxis: a craft has exactly two dimensions — action vs cognition, and acquisition (study) vs application (work) — so there are exactly four kinds of documentation, one per quadrant. When a page resists classification, use the compass: ask does this inform action or cognition? and does it serve the user's study or their work?

Before writing, identify which type of page you're creating. Each type has different rules.

The cardinal sin is mixing types. A tutorial that stops to explain architecture loses the learner. A reference page that teaches loses the practitioner looking up a parameter. An explanation page that includes step-by-step instructions belongs in a how-to guide. Blur happens between map neighbors — the most common conflation in software docs is tutorial ↔ how-to guide; the subtlest is reference examples growing into explanation. The axis separating tutorial from how-to is study vs work, never basic vs advanced. See references/diataxis.md for the boundary tests, per-type ground truths, and workflow guidance (guide, not plan — never scaffold four empty sections; improve one small thing at a time and let structure emerge).

Core Philosophy

Quick Reference: Critical Rules

Detailed Guidance by Topic

• Diátaxis ground truths: See references/diataxis.md for the compass, type-boundary tests (tutorial vs how-to, reference vs explanation), per-type principles sourced from diataxis.fr, iterative workflow, and structure at scale
• Documentation structure: See references/structure.md for site architecture, page templates, navigation config, shared content systems
• Narrative tone & explanation pages: See references/tone.md for voice, style, sentence patterns, jargon handling, and explanation/concept page guidance
• Tutorials & how-to guides: See references/guides.md for tutorial rules (learning-oriented), how-to guide rules (task-oriented), progressive disclosure, framework variants
• API references: See references/api-reference.md for parameter docs, return types, TypeScript presentation, OpenAPI, cross-referencing
• Vocs setup & syntax: See references/vocs.md for project init, config, markdown extensions, code annotations, twoslash, snippets, layouts
• Agent-readable docs: See references/agent-readable-docs.md for llms.txt, Markdown routes, MCP server, toMarkdown, markdown-audit, search priority