technical-writing

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