# Technical Writing

> Write clear, comprehensive technical documentation. Use when creating specs, architecture docs, runbooks, or API documentation. Handles technical specifications, system design docs, operational guides, and developer documentation with industry best practices.

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

---


# Technical Writing

## Quick Start

1. **Understand your audience** - See [writing-tips.md](references/writing-tips.md)
2. **Choose document type** - See [templates.md](references/templates.md)
3. **Write and review** - Follow guidelines below

## Document Types

| Type | Use For |
|------|---------|
| Technical Spec | Feature designs, technical decisions |
| Architecture Doc | System design, component overview |
| Runbook | Operations, deployment, troubleshooting |
| API Docs | REST/gRPC endpoints, integrations |
| Changelog | Release notes, version history |

## Core Guidelines

### Clarity
- Use simple, direct language
- One idea per sentence
- Define technical terms
- Avoid jargon when possible

### Structure
- Use hierarchical headings (H1, H2, H3)
- Break content into sections
- Use lists for multiple items
- Use tables for structured data

### Completeness
- Cover prerequisites
- Include error handling
- Document edge cases
- Explain why, not just how

## Templates

See [templates.md](references/templates.md) for:
- Technical specification template
- Architecture document template
- Runbook template
- API documentation template
- Changelog template

## Writing Tips

See [writing-tips.md](references/writing-tips.md) for:
- Active voice vs passive voice
- Concise language examples
- Breaking down complexity
- Common mistakes to avoid
- Audience-specific guidance
- Visual aid examples (Mermaid diagrams, code blocks)

## Review Checklist

- [ ] Clear purpose stated upfront
- [ ] Logical flow of information
- [ ] All terms defined
- [ ] Code examples tested
- [ ] Links work
- [ ] Diagrams are clear
- [ ] Consistent formatting
- [ ] Table of contents (if long)
- [ ] Last updated date