CHABOT

Documentation as product

4 minute read 914 words

For many developers, documentation is their first direct interaction with a product. A confusing quickstart can end an evaluation before the user reaches the API. DevRel, product, and technical writing therefore need explicit ownership of documentation work.

The audience problem

Every doc page is read by multiple audiences with different needs:

  • The new user who has never used your product.
  • The advanced user debugging a corner case.
  • The evaluator trying to decide if your product fits their needs.
  • The architect assessing your product against alternatives.
  • The AI assistant indexing your docs to answer questions about your product.

A single page cannot serve all of these. A documentation system can.

Diátaxis

Daniele Procida’s Diátaxis framework separates documentation into four types:

TypeGoalToneExample
TutorialsLearningGuided, sequential”Build your first chat app”
How-to guidesSolve specific problemConcise, recipe-style”How to authenticate with OAuth”
ReferenceLookupExhaustive, factualAPI reference, CLI flags
ExplanationUnderstandingDiscursive, conceptual”How our consensus algorithm works”

Each docs page should clearly be one of these. Mixing types is a recurring docs failure.

The minimum viable docs structure

For a launching developer product, the minimum docs are:

  1. Quickstart (a tutorial): 5 minutes to first hello world.
  2. Getting started (slightly more depth): first real feature usage.
  3. Concepts (an explanation): what the model is.
  4. API reference (reference): all endpoints / classes / methods.
  5. How-to guides (how-to): top 10 things users want to do.
  6. SDK docs (reference + tutorial mix per SDK).

Treat these six areas as the launch baseline. If one is omitted, identify how users will complete the corresponding task.

Time to first hello world

One of the most useful documentation metrics is time to first hello world (TTFHW). It measures the elapsed time from a developer arriving at your docs to having a working example produce visible output.

For most API products, a useful target is under 5 minutes. For complex platforms, use under 15 minutes. If the task takes longer than 30 minutes, identify which product, account, installation, or documentation step caused the delay.

Drivers of TTFHW:

  • Signup friction (account creation, credit card requirements).
  • API key generation friction.
  • SDK installation friction.
  • Working sample code.
  • Sandbox / playground availability.

Have a new hire with relevant background attempt the quickstart without help, record the elapsed time, and note each blocked or ambiguous step.

See Activation metrics.

OpenAPI / spec-first docs

For API products, generating reference docs from an OpenAPI / Swagger / GraphQL schema is now the default approach. Benefits:

  • Reference docs can be regenerated when the API specification changes.
  • Multiple output formats from one source (docs, SDK generators, mock servers, validators).
  • Machine-readable spec serves downstream tooling.

Tools:

  • Stoplight, Redocly, Mintlify, ReadMe, Bump.sh. Covered in Documentation platforms.
  • Postman. Also a primary surface for many developers.

Interactive elements

Interactive documentation can remove context switching and configuration from an evaluation:

  • Embedded sandboxes. CodeSandbox, StackBlitz, Sandpack.
  • Live API consoles. Try-it-now widgets with your API key.
  • Curl-to-code generators. Show curl example then auto-generate equivalent SDK code.
  • Switchable code samples. “View in Python | JavaScript | Go | Rust.”

SDK-specific documentation

Each SDK has its own docs sub-problem. Common pattern: a shared “concepts” layer with per-language tutorials and per-language reference.

Provide examples and references in each supported SDK’s language rather than routing every user through Python examples.

Versioning

For mature products, docs versioning is non-trivial:

  • API versioning with deprecation paths.
  • Docs for current version visible by default, with prior versions accessible.
  • Clear migration guides between versions.
  • Changelog that is actually useful.

Stripe documents its API-versioning model alongside migration and compatibility information.

Search helps users locate task-specific pages and exposes gaps in the information architecture:

  • Algolia DocSearch. Free for open source; commercial otherwise. Provides hosted search for documentation sites.
  • Mintlify built-in search, GitBook search. Adequate.
  • Custom search with proper relevance tuning: Expensive but often necessary at scale.

Track search-query logs to find subjects users seek but cannot locate or that the documentation has not covered.

AI-readiness

From 2024 onward, much of your docs traffic is AI agents on behalf of developers (ChatGPT, Claude, Cursor, Copilot). Practical implications:

  • Clear semantic structure. Headings, lists, code blocks.
  • One concept per page. AI agents work better with focused content.
  • Explicit versions and dates. AI agents need to know what’s current.
  • Complete runnable examples with all imports.
  • Clean URLs. Persistent URLs that survive site reorganisations.
  • Expose an llms.txt or equivalent index of canonical AI-readable pages.

See AI and LLMs in DevRel.

Doc culture

Documentation quality also depends on ownership and release practices:

  • Product and engineering ownership. Product managers and engineers include documentation in feature planning and review.
  • Doc reviews part of code review. Shipping a feature without docs is shipping a feature half-done.
  • A dedicated docs owner per area. Shared contribution still needs one person accountable for review and maintenance.
  • A docs roadmap. Quarterly investments in documentation quality.

Examples of companies applying these practices include Stripe, Twilio, Auth0, DigitalOcean, Cloudflare, Postman, Algolia, and MongoDB.

See also