# Technical Documentation Examples: 12 Structures and Templates Twelve technical documentation examples for SaaS and API teams, with practical structures, small templates, and the job each document should do. Faizan Khan 2026-08-28 • 13 min read Most technical documentation templates fail for the same reason: they begin with a page layout instead of a reader's job. A quickstart and an API reference can use the same visual components, but they are not interchangeable. One gets a developer to a first success. The other answers exact questions after the developer has already started building. This guide covers twelve technical documentation examples, the structure each one needs, and the common mistake that makes it less useful. ## Technical Documentation Examples at a Glance | Document type | Primary job | Success test | | --------------------------- | ------------------------------------------------- | ------------------------------------------------------------ | | README | Explain the project and the first path | A new reader knows whether to continue | | Quickstart | Produce one successful result | The result works from a clean environment | | Concept guide | Build a correct mental model | The reader can predict system behavior | | API endpoint reference | Define one operation precisely | A request can be built without guessing | | Authentication guide | Get a valid credential into a request | The first authenticated request succeeds | | Error catalog | Turn failures into next actions | The reader can diagnose and recover | | SDK guide | Show the idiomatic language workflow | Code runs with the documented version | | CLI reference | Make commands discoverable and scriptable | Flags, output, and exit behavior are clear | | Webhook guide | Explain an asynchronous contract | Events can be verified, retried, and deduplicated | | Migration guide | Move between versions safely | Breaking changes and rollback are explicit | | Changelog | Explain what changed and who is affected | A team can decide whether to act | | Troubleshooting runbook | Shorten recovery from known failures | Symptoms lead to checks and fixes | The rest of the article gives a compact template for each. ## 1. README Example A README is an orientation document, not the complete manual. It should answer four questions quickly: 1. What is this? 2. Who is it for? 3. What is the shortest working path? 4. Where does deeper documentation live? ```markdown # Acme Events SDK Send product events from Node.js services to Acme. ## Install ```bash npm install @acme/events ``` ## First event ```ts import { Acme } from "@acme/events"; const client = new Acme({ apiKey: process.env.ACME_API_KEY }); await client.track("account.created", { accountId: "acc_123" }); ``` ## Next - [Authentication](/authentication) - [Event schema](/events/schema) - [Retries](/events/retries) ``` **Common failure:** turning the README into a copy of the marketing page. A developer opening a repository usually needs an install command and a verified example, not another value proposition. ## 2. Quickstart Example A quickstart should optimize for one complete result. It should not teach every concept on the way. ```markdown # Send your first event You will create an API key, install the Node SDK, send one event, and verify it in the dashboard. ## Before you start - Node.js 20 or newer - An Acme workspace with permission to create API keys ## 1. Create an API key ... ## 2. Install the SDK ... ## 3. Send an event ... ## 4. Verify the result Open **Events > Live** and confirm `account.created` appears. ``` A good quickstart names prerequisites before step one and shows how to verify the outcome at the end. Without verification, a reader cannot tell whether the tutorial worked or merely stopped producing errors. ## 3. Concept Guide Example Concept pages explain how the system behaves. They should help a reader make decisions that are not reducible to one command. ```markdown # Delivery guarantees Acme accepts events at least once. A successful response means the event was persisted, not that every downstream destination processed it. ## What can be duplicated Retries can deliver the same event more than once. Use `event_id` as the idempotency key in consumers. ## Ordering Ordering is preserved within one `account_id`, but not across accounts. ## Choose a retry policy | Failure | Retry? | Reason | |---|---:|---| | 429 | Yes | Temporary rate limit | | 400 | No | Request must change | | 503 | Yes | Temporary service failure | ``` **Common failure:** writing an abstract overview with no decision rules. A useful concept page changes what the reader does. ## 4. API Endpoint Reference Example An endpoint page is a contract. It needs the information required to construct, send, and interpret one operation. ```markdown # Create an event `POST /v1/events` Creates one event for an account. ## Request | Field | Type | Required | Description | |---|---|---:|---| | `event_id` | string | yes | Unique idempotency key | | `name` | string | yes | Dot-separated event name | | `account_id` | string | yes | Owning account | | `properties` | object | no | Event-specific values | ## Response `202 Accepted` means the event was persisted for asynchronous delivery. ## Errors - `400 invalid_event_name` - `401 invalid_api_key` - `409 duplicate_event_id` ``` If the reference is generated from OpenAPI, keep the spec-backed fields generated. Put product explanation, examples, and cross-endpoint workflows around that generated contract rather than editing generated output by hand. ## 5. Authentication Guide Example Authentication documentation is often spread across a dashboard tooltip, a security page, and an endpoint example. Put the whole first-request path in one place. ```markdown # API authentication Acme uses bearer API keys for server-to-server requests. ## Create a key 1. Open **Settings > API keys**. 2. Choose the narrowest required scopes. 3. Store the secret once; Acme does not show it again. ## Send the key ```bash curl https://api.acme.test/v1/events \ -H "Authorization: Bearer $ACME_API_KEY" ``` ## Environments Test keys start with `test_`. Production keys start with `live_`. ## Common failures | Status | Cause | Fix | |---|---|---| | 401 | Missing or invalid key | Replace the bearer token | | 403 | Missing scope | Create a key with the required scope | ``` Never put a real secret in an example. Explain scope, environment, rotation, and the exact failure modes next to the first request. ## 6. Error Documentation Example An error catalog should connect a machine-readable error to a human next step. ```markdown # API errors Every error response includes a stable `code`, a request-specific `message`, and a `request_id` support can use for tracing. ```json { "code": "rate_limit_exceeded", "message": "Too many requests for workspace ws_123", "request_id": "req_456" } ``` | Code | Retry | Next action | |---|---:|---| | `invalid_request` | no | Correct the named field | | `rate_limit_exceeded` | yes | Back off using the response headers | | `service_unavailable` | yes | Retry with jitter | ``` **Common failure:** documenting only HTTP statuses. `400` is a transport category; a stable error code is what software and support teams can act on. ## 7. SDK Documentation Example SDK documentation should show the idiomatic workflow for one language, not mechanically transliterate HTTP requests. ```markdown # Node SDK ## Install ```bash npm install @acme/events ``` ## Configure one client Create the client once and reuse it. The client manages connection pooling and retries safe failures by default. ```ts export const acme = new Acme({ apiKey: process.env.ACME_API_KEY, timeout: 5_000, }); ``` ## Handle an API error ```ts try { await acme.events.create(input); } catch (error) { if (error instanceof Acme.RateLimitError) { // Respect error.retryAfter before retrying. } } ``` ``` Pin the documented SDK version or show when the example was verified. Generated SDKs still need human-written guidance about lifecycle, retries, pagination, and language-specific conventions. ## 8. CLI Documentation Example CLI documentation has two readers: a person at a terminal and a script that depends on stable behavior. ```markdown # `acme events send` Send one event from a file or standard input. ## Usage ```bash acme events send --file event.json cat event.json | acme events send --stdin ``` ## Flags | Flag | Default | Description | |------------|---------|--------------------------------------| | `--file` | none | JSON input file | | `--stdin` | false | Read JSON from standard input | | `--output` | `text` | `text` or `json` | ## Exit codes | Code | Meaning | |---:|-----------------------------------------| | 0 | Event accepted | | 2 | Invalid arguments or input | | 3 | Authentication failed | | 4 | Remote API failed | ``` See the [OpenAPI-to-CLI workflow](/content/cli/index.html) for the larger question: which parts can be generated from a spec and which behavior still needs explicit CLI design. ## 9. Webhook Documentation Example Webhook docs need to explain the contract around delivery, not just list event names. ```markdown # Receive webhooks ## Verify the signature Use the raw request body and the `Acme-Signature` header. Reject requests whose timestamp is more than five minutes old. ## Acknowledge quickly Return a 2xx response within five seconds. Queue slow work for later. ## Handle retries Acme retries for 24 hours with exponential backoff. The same `event_id` can be delivered more than once. ## Test locally ```bash acme webhooks listen --forward-to localhost:3000/webhooks/acme ``` ``` Include signature verification, timing, retries, ordering, deduplication, and a local test loop. An event schema alone is not a webhook guide. ## 10. Migration Guide Example A migration guide should make risk visible. ```markdown # Migrate from API v1 to v2 ## What changed - `customer` is now `account` - timestamps use RFC 3339 strings instead of Unix seconds - list responses use cursor pagination ## Migration order 1. Accept both timestamp formats in consumers. 2. Move list calls to cursor pagination. 3. Replace `customer_id` with `account_id`. 4. Switch traffic to v2. 5. Remove the compatibility code after verification. ## Rollback Keep the v1 key active until v2 traffic has passed production checks. ``` Do not hide breaking changes inside a changelog. A migration document needs sequence, compatibility window, verification, and rollback. ## 11. Changelog Example A useful changelog explains impact, not only implementation. ```markdown # 2026-08-28 ## Cursor pagination for event lists `GET /v1/events` now returns `next_cursor`. Offset pagination remains available until 2026-11-30. **Who is affected:** integrations that request more than one page. **Action:** update the loop to pass `next_cursor` on the next request. **No action:** integrations that fetch only the first page. ``` The key fields are who is affected, what action is required, and the deadline. A Git commit message is not a release note. ## 12. Troubleshooting Runbook Example Troubleshooting pages work best when they start with symptoms and observable checks. ```markdown # Events do not appear in the dashboard ## 1. Check the response - `202`: continue to delivery checks - `401`: replace the API key - `429`: wait for the reset time ## 2. Confirm the environment Test events and production events appear in separate workspaces. ## 3. Search by request ID Run: ```bash acme requests get req_456 ``` ## 4. Contact support Send the request ID. Do not send the API key or full authorization header. ``` **Common failure:** organizing troubleshooting around internal components. Readers arrive with symptoms, not your service topology. ## A Reusable Technical Documentation Template When no specialized format fits, use this small structure: ```markdown # [Task or concept] [One paragraph defining the outcome or behavior.] ## Before you start - [Requirement] - [Permission] - [Supported version] ## [First meaningful step or concept] [Exact instruction or explanation.] ```language [Verified example] ``` ## Verify the result [Observable success condition.] ## Failures and recovery | Symptom or error | Cause | Next action | |---|---|---| ## Related documentation - [One prerequisite] - [One next task] - [One reference page] ``` Use the template as a review checklist, not as a reason to force every page into the same shape. ## How to Evaluate Your Own Examples Pick one task and test it from a clean environment. Check whether the page includes: - the intended outcome in the first paragraph - prerequisites before the instructions - a complete, current example - an observable success condition - named failures and recovery steps - links to one prerequisite and one next task Then run the page through [DocsAgent Score](/content/tools/docsagent-score/index.html), check its crawlability and search signals with the [Docs SEO Checker](/content/tools/docs-seo/index.html), or compare its delivery and structure with the [public documentation benchmark](/content/benchmarks/docs/index.html). For API-specific patterns, continue with [API documentation examples scored for onboarding and AI readability](/content/blog/api-documentation-examples/index.html). For the workflow behind generated references, SDKs, and CLIs, see [API documentation automation](/content/features/api-docs-automation/index.html).