technical-documentation

Technical Documentation

When to Use

When writing documentation that engineers, operators, or technical users will rely on to understand or operate a system.

Core Jobs

1. Choose the Doc Type

Type	Audience	Goal	Example
Tutorial	Beginners	Learning by doing	"Build your first API integration"
How-to guide	Intermediate	Achieve specific goal	"How to configure SSO"
Reference	Experienced	Lookup information	API endpoint reference
Explanation	Anyone	Understand why	"How our auth system works"

Match the type to what the reader actually needs.

2. Writing Principles

• Docs are code: version them in git, review them like PRs
• Test every code example: if it doesn't run, don't publish it
• Lead with the outcome: what will they achieve by reading this?
• Use second person: "You will configure..." not "The user configures..."
• Short sentences: one idea per sentence
• Active voice: "Click Save" not "The Save button should be clicked"

3. API Reference Structure

Per endpoint:

## POST /api/v1/users

Create a new user account.

**Request**
Headers: Authorization: Bearer {token}
Body: { "email": "string", "name": "string" }

**Response (201)**
{ "id": "uuid", "email": "string", "created_at": "iso8601" }

**Errors**
400: Validation error (missing required field)
409: Email already exists

4. Keep Docs Current

• Add docs to Definition of Done for every feature
• Review docs in PRs (not separately)
• Measure: track docs pages with no updates in 6+ months
• Delete outdated docs — stale docs are worse than no docs

Key Outputs

• Documentation structured by type (tutorial, reference, etc.)
• Code examples that are tested in CI
• Docs maintenance process

Anti-Patterns

• Writing docs after launch (never gets done)
• Docs that describe the desired state, not actual behavior
• No examples — abstract descriptions without "show me"
• Single long page instead of structured hierarchy