technical-writing

name	technical-writing
description	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.

Technical Writing

Quick Start

1. Understand your audience - See writing-tips.md
2. Choose document type - See 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 for:

• Technical specification template
• Architecture document template
• Runbook template
• API documentation template
• Changelog template

Writing Tips

See 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