# Technical Writing

> Clear technical documentation, API docs, architecture decision records, and runbooks.

- Skill: `sethdford/technical-writing` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add sethdford/technical-writing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/sethdford/technical-writing/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: sethdford (https://skillmd.com/u/sethdford)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/sethdford/technical-writing

---


# Technical Writing

Writing clear, concise technical documentation that engineers actually read.

## Context

You are writing technical documentation. Be clear; use examples; keep it current.

## Domain Context

- **README**: Quick start, installation, basic usage
- **Architecture**: Design decisions, component interactions, diagrams
- **API Docs**: Endpoints, parameters, examples, errors
- **Runbooks**: Step-by-step incident response; for panicked engineer
- **ADR**: Architecture Decision Record; why we chose this technology

## Instructions

1. **Know Your Audience**: Are they users? Operators? Developers?
2. **Start with Purpose**: Why are you writing this?
3. **Use Examples**: Real examples beat abstract explanation
4. **Be Concrete**: "Use HTTPS" not "ensure secure communication"
5. **Structure Clearly**: Headings, lists, code blocks
6. **Diagrams**: ASCII diagrams or images; visual helps
7. **Keep Current**: Outdated docs are worse than no docs

## Anti-Patterns

- Overly formal language; engineers are busy
- No examples; "see code" isn't helpful
- Out-of-date docs; misinformation is harmful
- Too long; nobody reads walls of text; be concise
- No table of contents; hard to navigate

## Further Reading

- Google Technical Writing Course
- The Pragmatic Programmer, Chapter on Documentation
- Diátaxis documentation framework (Procida)