Technical Writing

Creates professional technical documentation with clear structure, appropriate detail level, and user-focused content.

Workflow

1. Identify Documentation Type

Determine which type of documentation is needed:

• API Documentation – REST, GraphQL, webhooks, authentication
• User Guides – Features, how-tos, troubleshooting
• Tutorials – Learning-focused with hands-on examples
• Architecture Documents – System design, technical decisions
• README Files – Project overview, quick start
• Release Notes – Changes, migrations, breaking changes
• Technical Specifications – Requirements, constraints

For detailed templates and patterns: Load documentation-types-and-workflows.md

2. Gather Context

Collect essential information before writing:

• Audience – Developers, end-users, managers, administrators
• Technical depth – Beginner, intermediate, advanced
• Scope – Codebase/APIs/systems to document
• Standards – Style guides or organizational requirements
• Related docs – Existing documentation to reference or integrate with

3. Structure Content

Apply clear organization principles:

• Lead with overview/introduction
• Use descriptive heading hierarchy (H1 → H2 → H3)
• Include table of contents for documents with >3 sections
• Group related information logically
• Place examples immediately after concepts
• Add diagrams/visuals for complex workflows

4. Write Clear Content

Follow core writing principles:

• Active voice – “The API returns…” not “The response is returned…”
• Specificity – “Response time < 200ms” not “Fast response”
• Define acronyms – “API (Application Programming Interface)” on first use
• Consistent terminology – Same terms throughout document
• Imperative instructions – “Run the command” not “You should run…”
• Show examples – Provide code/output for every concept

For comprehensive style guidance: Load writing-guidelines.md

5. Add Code Examples

Code example requirements:

• Specify language in code blocks: python,javascript
• Show complete, runnable examples (not fragments)
• Include input/output pairs
• Add explanatory comments for complex logic
• Test all code before publishing

6. Review and Validate

Quality assurance checklist:

• ✓ Verify technical accuracy
• ✓ Test all code examples
• ✓ Check clarity and completeness
• ✓ Ensure consistent terminology
• ✓ Validate all links and references

Documentation Templates

README Files

Essential components for project documentation:

# Project Name
Brief description of what the project does

## Features
- Key feature 1
- Key feature 2
- Key feature 3

## Installation
[step-by-step installation commands]

## Quick Start
[minimal working example]

## Configuration
[environment variables or config options]

## License
[license type]

Release Notes

Structure for version releases:

# Version X.X.X - YYYY-MM-DD

## Summary
[High-level overview of this release]

## New Features
- Feature description (#issue-number)
- Feature description (#issue-number)

## Bug Fixes
- Fix description (#issue-number)
- Fix description (#issue-number)

## Breaking Changes
⚠️ **Change that breaks compatibility**
Migration guide: [step-by-step migration instructions]

## Deprecations
- Deprecated feature (will be removed in vX.X)

Quality Standards

Documentation quality checklist before publishing:

• Accuracy – All technical details are correct
• Completeness – All necessary topics covered
• Clarity – Target audience can understand content
• Examples – Working code included and tested
• Structure – Logical organization with clear headings
• Consistency – Terminology and formatting consistent
• Links – All hyperlinks are valid
• Grammar – No spelling or grammatical errors
• Current – Version numbers and dates up-to-date

Common Pitfalls to Avoid

1. Assuming knowledge – Define all acronyms and technical terms
2. Vague instructions – Be specific with concrete examples
3. Missing error scenarios – Document errors and solutions
4. Outdated examples – Test and update code regularly
5. Inconsistent terminology – Use identical terms throughout
6. Missing prerequisites – List all requirements upfront
7. Poor formatting – Use headings, lists, code blocks properly
8. No examples – Always include working code samples
9. Wrong audience level – Match technical depth to readers
10. Dense text – Break into scannable sections with clear headings

Reference Files

• documentation-types-and-workflows.md – Complete templates and patterns for API docs, user guides, tutorials, architecture docs, and technical specifications
• writing-guidelines.md – Detailed style rules for clarity, active voice, specificity, consistency, heading hierarchy, code formatting, and lists