Documentation

Lee Robinson

Here’s how to build incredible developer documentation:

Documentation design example

1. Fast

  • Pages need to load as fast as possible (prefer static pages).
  • Optimize image, font, and script loading.
  • Search needs to be extremely fast to load and view results.

2. Readable

  • Be concise (make every token count).
  • Avoid technical jargon and idioms.
  • Optimize for skimming (good use of bold, italic, lists, headings, images, etc.).
  • Keep the first-time experience simple and slowly reveal complexity.
  • Ensure docs have many code examples you can copy/paste or run.

3. Helpful

  • Always document workarounds even if it’s a product gap.
  • Make it easy for readers to leave feedback on docs (e.g. typos).
  • Automate checking for broken links on git pushes.
  • Create learning material with a structured curriculum.
  • For any breaking change, include codemods and migration guides.

4. AI-native

Spoiler alert: most bot traffic to docs now comes from AI crawlers.
  • Prefer cURL over "click" if possible.
  • Prefer prompts over tutorials.
  • Add an "Ask AI" sidebar that can reference your docs pages.

5. Agent-ready

  • Make it easy to copy/paste content in AI chatbots as Markdown.
  • Support viewing pages as Markdown (just add .md to the URL).
  • Serve Markdown files when Accept: text/markdown is requested.
  • Serve an llms.txt file as a directory of Markdown files.
LLMs documentation example

6. Polished

  • Buttons should have generous hit areas (especially sidenavs).
  • Sidebars should retain scroll position and expanded state.
  • Ensure good active/hover states for elements.
  • Add dynamic OG images.
Dynamic OG images example
  • Every heading and section should be linkable with stable anchors.
Linkable headings example
  • Related guides, APIs, and examples should reference and cross-link each other.
  • Add metadata/canonical tags to ensure docs show up cleanly in search.

7. Localized

  • Don’t display /en in the URL by default.
  • Use server-side routing to serve the correct language.
  • Localize static strings and docs content.
Internationalization example

8. Responsive

9. Accessible

  • Ensure all images have alt text.
  • Respect prefers-reduced-motion system settings.

10. Universal

  • Ship docs-as-code for libraries with JSDoc (or as a package).
  • Ship your docs as an MCP server like Context7.
  • Ship your docs in your library node_modules.
  • Ship rules files (like AGENTS.md) with your product.
  • Ship evals and recommend specific models for your product.