technical-writing

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](references/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](references/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

README Files

Essential components for project documentation:

```markdown

# Project Name

Brief description of what the project does

• Key feature 1
• Key feature 2
• Key feature 3

[step-by-step installation commands]

[minimal working example]

[environment variables or config options]

[license type]

```

Release Notes

Structure for version releases:

```markdown

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

[High-level overview of this release]

• Feature description (#issue-number)
• Feature description (#issue-number)

• Fix description (#issue-number)
• Fix description (#issue-number)

⚠️ Change that breaks compatibility

Migration guide: [step-by-step migration instructions]

• Deprecated feature (will be removed in vX.X)

```

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

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

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