Should we use a docs platform or roll our own?

Use a platform. Docusaurus (open source) or Mintlify/ReadMe/GitBook (hosted) get you 90% of the way in a day. Rolling your own docs site is a project that eats 3 months and produces something worse. Reserve custom builds for products where docs are the product (Stripe, Twilio scale).

Where should docs live — subdomain or path?

Path (docs.example.com is fine, example.com/docs is fine — either works). What matters more: shared search, shared header, shared auth for private docs. Do not fragment across multiple platforms — 'guides here, reference over there, changelog on Notion' is death by a thousand tabs.

What about AI/LLM answer engines?

Publish a llms.txt file linking to your key docs; expose Markdown versions of pages (adding .md to URLs, or a /raw endpoint); publish an OpenAPI spec at a stable URL. Increasingly, engineers ask ChatGPT/Claude how to use your API before visiting your docs. Being answered correctly by an LLM depends on your content being machine-readable and consistent.

Developer Documentation: Reference, Guides, Quickstarts

For any product with a developer surface — API, SDK, webhook, integration — the docs are the sales page, the onboarding, and the support system in one.

Developer Documentation: The Sales Surface Engineers Read Before Talking to You

Developer documentation is the primary interface between a technical product and the engineers evaluating, integrating, and maintaining code against it. Unlike marketing pages that persuade, docs must inform completely and honestly — an ambiguous parameter description or a broken quickstart tells an experienced engineer everything they need to know about how the product is built. Investing in docs is investing in evaluation win-rate and support deflection.

The four documentation modes (Diátaxis)

The Diátaxis framework separates docs into four purposes: (1) Tutorials — learning-oriented, walk a beginner from zero to first success. (2) How-to guides — task-oriented, help someone accomplish a specific goal. (3) Reference — information-oriented, describe every endpoint/parameter/error exhaustively. (4) Explanations — understanding-oriented, describe why the system is designed the way it is. Confusing modes is the #1 docs failure: reference material buried in tutorials, tutorials pretending to be reference. Label each page by mode; enforce structure per mode.

The quickstart is the entire evaluation

An engineer's first 15 minutes decide whether your product enters their POC or gets closed. The quickstart must: (1) require zero setup beyond an API key; (2) produce a visible success (a returned JSON, a webhook fired, a dashboard row) within 5 minutes; (3) work in the reader's language (offer curl + Python + Node minimum); (4) link to the next 3 things they'd want to do. Test the quickstart weekly against a fresh environment — 'happy path decay' is real; a quickstart that worked in Q1 often doesn't in Q3 after API changes.

Reference docs from the spec, not by hand

Generate reference from OpenAPI (REST), Protobuf (gRPC), or GraphQL schema files. Handwritten reference goes stale within one release. Tooling: Stoplight, ReadMe, Redoc, Mintlify, Fern, Bump.sh, or Docusaurus with an OpenAPI plugin. Every endpoint page shows: method + path, description, all parameters (with types, required/optional, constraints, examples), request example, response example, and error responses. Enforce doc coverage in CI: an endpoint added without a description block fails the build.

Search, versioning, and code samples

Docs sites live and die by search. Instant client-side search (Algolia DocSearch, Typesense) with keyword relevance for parameter names and error codes. Version the docs alongside the API — engineers on v1 must find v1 docs by default with a clear switcher to v2. Code samples in at least the top 3 languages of your audience, tested in CI against the actual API — samples that don't compile are the fastest way to lose trust. Keep an examples repo (GitHub) that mirrors the docs and can be cloned to run locally.

Doc ops: who writes, who reviews, when

Docs are engineering work. Every user-facing API change PR includes docs updates in the same PR — enforced by a CODEOWNERS rule on the docs directory or a check that a corresponding docs file changed. Technical writers, when you can afford one, turn engineer-drafted docs into polished, cohesive prose — but engineers write the first draft because they own the truth. Ship a weekly changelog with breaking changes clearly labeled. Instrument docs analytics (search terms, page dwell, 404s) and treat top search terms as a product backlog signal.

Frequently asked questions

Should we use a docs platform or roll our own?: Use a platform. Docusaurus (open source) or Mintlify/ReadMe/GitBook (hosted) get you 90% of the way in a day. Rolling your own docs site is a project that eats 3 months and produces something worse. Reserve custom builds for products where docs are the product (Stripe, Twilio scale).
Where should docs live — subdomain or path?: Path (docs.example.com is fine, example.com/docs is fine — either works). What matters more: shared search, shared header, shared auth for private docs. Do not fragment across multiple platforms — 'guides here, reference over there, changelog on Notion' is death by a thousand tabs.
What about AI/LLM answer engines?: Publish a llms.txt file linking to your key docs; expose Markdown versions of pages (adding .md to URLs, or a /raw endpoint); publish an OpenAPI spec at a stable URL. Increasingly, engineers ask ChatGPT/Claude how to use your API before visiting your docs. Being answered correctly by an LLM depends on your content being machine-readable and consistent.

Related fundraising guides (40)

Investor directory · Fundraising library · Articles A–Z · Company funding database