Every documentation guide says the same thing: write for the reader, keep it scannable, show working code. Then it stops short of showing you a single page worth copying. This article does the opposite. Below are seven technical documentation examples, all public, accessible, and active. Each one gets a note on what it does well. Each gets one template pattern worth stealing.
Each example was picked for a different reason. Stripe is here for the page architecture. Twilio for breadth. Linear for restraint. The comparison table at the end maps documentation types to the dimensions that matter most when choosing a format.
What makes technical documentation good?
Good technical documentation lets a competent reader complete a real task without leaving the page. That is the working definition behind every example below. It means three things in practice. The page is structured around an outcome, not a feature list. Every code sample runs as written. The navigation reflects how the product is used, not how the codebase is organized.
The pages that fail this test usually share one cause. They were written by feature, not by task. Consider a reader trying to "set up webhooks". Feature-organized docs make that reader assemble it from a page on events, a page on signatures, and a page on retries. The examples below avoid the trap in different ways.
1. Stripe: the two-column standard
Stripe's API reference set the dominant pattern for developer documentation: prose on the left, runnable code on the right, with language tabs at the top of the code column. The two columns stay in sync as you scroll. The parameter you are reading about is the parameter highlighted in the example.
What to copy: the side-by-side layout itself. A reader reads about a parameter and sees it used in a real call. No context-switching. Tabs let the same page serve curl users, Node users, and Python users without forks.
What to avoid: copying the layout without the underlying writing discipline. Stripe's prose is short. Each parameter gets a single sentence. The layout fails the moment the left column becomes a wall of text.
Teams building a Stripe-style reference from an OpenAPI spec can generate the page skeleton instead of hand-writing it. The API documentation guide covers that workflow.
2. Twilio: quickstarts in every language
Twilio's documentation committed early to a "quickstart per language" model. Every product has its own quickstart, and each quickstart is rewritten — not auto-translated — for Node, Python, PHP, Java, C#, Ruby, and Go.
What to copy: the willingness to maintain N copies of the onboarding path when N matters. For a SaaS API targeting backend engineers, that cost is justified. The alternative is a single quickstart with language tabs. It always reads slightly off in five of seven languages.
The pattern only works because Twilio invested in the editorial process to keep the copies in sync. Without that investment, language-specific quickstarts go stale. A stale quickstart is a liability, not an asset.
3. Tailwind CSS: the searchable utility reference
Tailwind's docs treat the utility list as the navigation. You search "padding." You land on a page with every padding utility, a live preview, and the underlying CSS. There is no narrative section trying to teach you the framework. The reference is the teaching.
What to copy: the assumption that a developer reading reference docs already knows what they are trying to do. They need fast lookup, not exposition. Every page renders the actual output next to the class name. The reader verifies the result before pasting it into their code.
This works because Tailwind is a flat-namespace product. Frameworks with deeper conceptual layers (state, lifecycle, async behavior) cannot do reference-only. They need conceptual pages too.
4. Linear: less is the feature
Linear's documentation is short. Pages rarely exceed a few hundred words. Where most B2B SaaS docs explain every possible permutation, Linear documents the intended path and stops.
What to copy: the editorial confidence to say "do it this way" instead of listing six approaches. Documentation that hedges every recommendation leaves the reader undecided. Linear chose strong defaults in the product, then matched them in the docs.
The hidden cost is that opinionated docs require an opinionated product. A flexible product with weak defaults cannot be documented in this style. The style orphans common use cases. If the product gives the user three valid paths, the docs cannot in good faith pick one.
5. Vercel: task-based, outcome-first
Vercel's docs organize around what you want to accomplish: deploy a Next.js app, set up a custom domain, configure a build. The reference material exists, but it is not the primary navigation.
What to copy: the information architecture. The top-level navigation is a list of outcomes. Inside each outcome, the page walks through the steps. It links out to reference material only where needed. A reader finds the right page without knowing the internals of the system.
Compare this with documentation organized by API surface or product module. Those structures serve writers, not readers. The writer knows which team owns webhooks. The reader knows they need to handle a webhook.
6. React: interactive by default
The new React docs embed working sandboxes in nearly every conceptual page. You read about state, then change the value and watch the component re-render. No copy-paste, no setup, no separate playground.
What to copy: the use of interactive examples to short-circuit explanation. Two paragraphs explaining a hook lose to one paragraph plus a sandbox the reader can break. Where behavior matters more than syntax, the sandbox is the documentation.
The cost is real. Maintaining a sandbox runtime inside the docs site is engineering work, not a publishing task. Smaller teams should reach for static GIFs or recorded screen captures first.
7. Django: the tutorial as onboarding
Django's official tutorial walks a new user through building a working poll app across seven parts. It is one continuous narrative — not a list of disconnected how-tos.
What to copy: the use of a single end-to-end project as the onboarding spine. By the end, the reader has touched models, views, templates, the admin, and the test framework. They arrive in the order Django expects them to be learned. The tutorial does the framework's marketing for it.
The pattern only works when the team can commit to keeping the tutorial running across versions. Django has done this for over a decade. A stale tutorial is a worse first impression than no tutorial at all.
Documentation type comparison
The seven examples above span four broad documentation types. Each type serves a different reader intent. Each demands different editorial choices. The table below compares them across the dimensions that matter most when picking a format.
| Dimension | API reference | User guide | Runbook | Tutorial |
|---|---|---|---|---|
| Primary reader | Developer integrating an API | End user completing a task | On-call engineer or operator | New user learning the product |
| Structure | Endpoint/method per page, parameter tables | Task-based pages grouped by outcome | Step-by-step procedures with decision trees | Linear narrative building a single project |
| Code examples | Required — every endpoint needs a runnable call | Optional — only where the task involves code | Required — exact commands to run in production | Required — builds cumulatively across sections |
| Maintenance cost | High — must stay in sync with every API release | Medium — updates when workflows change | High — stale runbooks cause outages | Medium — must run against current version |
| Best example above | Stripe | Vercel | (operational, not covered) | Django |
| When to skip it | Internal-only API with < 5 consumers | Product with strong defaults (use Linear style) | Team < 3 engineers with no on-call rotation | Product too simple to need guided onboarding |
Patterns worth copying
Across the seven examples, a small set of patterns repeats:
- One outcome per page. The page is named for what the reader is trying to do, not for the part of the product it documents.
- Working code, not pseudocode. Every snippet runs as-is in the language tab the reader picked, with the imports included.
- Reference and conceptual material are separated. A how-to does not double as the API reference. Each links to the other.
- Fact boxes at the top. Versions, browser support, plan tiers, parameters — visible before the prose, not buried inside it.
- Strong defaults in the writing. A single recommended path, with alternatives below it if needed. Not five options ranked equally.
A team that adopts even three of these patterns will produce documentation a step better than what most users encounter today. Tooling is the smaller half of the decision. The technical writing software comparison covers the options once the editorial model is chosen.
Anti-patterns worth avoiding
The same set of mistakes shows up across docs that read as "fine" but never quite work for the reader:
- Documentation organized by product team. The reader does not know which team owns webhooks. They know they want to handle a webhook.
- Code samples that omit the imports. A snippet that cannot be pasted into a fresh file is not a sample. It is a hint.
- Pages that promise a quickstart and deliver a tour. A quickstart ends with a working thing. A tour ends with a list of links.
- Reference pages with no examples. Parameter tables are necessary and insufficient. The reader needs at least one full request to anchor the table to.
- Conceptual pages that explain everything except the one decision the reader has to make. Architecture diagrams are not a substitute for "use X when Y."
The shared thread: each anti-pattern shifts work from the writer to the reader. Good documentation moves it the other direction.
Frequently asked questions
What is technical documentation?
Technical documentation is structured writing that explains how a product, system, or API works so that a reader can complete a specific task. It includes API references, user guides, tutorials, runbooks, and architecture docs. The defining trait is that the reader arrives with a goal and the page either helps them finish it or fails. Unlike marketing copy or blog posts, technical documentation is measured by whether the reader can act on it, not by whether they enjoyed reading it.
What makes good technical documentation examples?
Good examples share three traits: the page is organized around an outcome rather than a feature list, every code sample runs as written, and the navigation reflects how the product is used rather than how the codebase is organized. Stripe, Vercel, and Linear each demonstrate this in different styles. The common thread is editorial discipline — short prose, working code, and a single recommended path per page.
What tools do technical documentation teams use?
Tooling varies widely. Stripe uses internal tooling. Tailwind uses Next.js with MDX. Linear runs a custom static site. React's docs use Next.js with embedded sandboxes. The pattern is that each team chose tooling that fits its editorial model — not the other way around. For teams that want structured authoring without building the stack themselves, a component content management system is the alternative. The tool matters less than the editorial process behind it.
How long should technical documentation be?
As long as the task requires and no longer. Linear's docs prove that pages under 500 words can fully document a task when the product has strong defaults. Django's tutorial proves that 10,000 words across seven parts work when the goal is end-to-end onboarding. The variable is the task, not the page. A page that covers one outcome completely in 300 words is better than a page that covers three outcomes partially in 2,000 words.
Who writes technical documentation?
Technical writers, developer advocates, and engineers all contribute. In smaller companies, engineers typically write the first draft and a technical writer edits for clarity and consistency. In larger organizations, dedicated documentation teams own the content with subject-matter experts reviewing for accuracy. The best results come from pairing domain knowledge (engineers) with communication skill (writers), regardless of who holds the pen.
How do you organize technical documentation?
Organize by outcome, not by product surface. Vercel's top-level navigation lists things a user wants to do: deploy, configure a domain, set up environment variables. Each outcome page walks through the steps and links to reference material where needed. Organizing by API module or product team reflects the org chart, not the reader's question. Start with a list of the ten tasks your users perform most frequently and make each one a top-level page.