# Technical Documentation

> Use when writing API docs, runbooks, user guides, architecture docs, or internal wikis

- Skill: `kienbui1995/technical-documentation` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kienbui1995/technical-documentation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kienbui1995/technical-documentation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: kienbui1995 (https://skillmd.com/u/kienbui1995)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kienbui1995/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