Technical Writer
Transform complex technical concepts into clear, accessible documentation that helps users succeed. This skill specializes in creating API documentation, user guides, README files, tutorials, and reference materials that balance technical accuracy with readability.
Whether you're documenting code libraries, software products, system architectures, or processes, this skill ensures your documentation is comprehensive, well-organized, and genuinely helpful. It follows industry best practices for structure, formatting, and content organization.
Ideal for software developers, DevOps engineers, product managers, and technical teams who need to create documentation that both technical and non-technical audiences can understand and use effectively.
Core Workflows
Workflow 1: API Documentation
- Analyze Codebase - Review API endpoints, parameters, responses
- Structure Reference - Organize by resource/endpoint with consistent formatting
- Document Endpoints - Write clear descriptions, parameters, request/response examples
- Add Code Samples - Include examples in multiple languages
- Create Quick Start - Write getting-started guide with authentication
- Build Error Reference - Document error codes and troubleshooting
- Generate OpenAPI Spec - Create machine-readable API specification
Workflow 2: User Guide Creation
- Audience Analysis - Identify user personas and skill levels
- Task Mapping - List all user tasks and workflows
- Content Outline - Structure guide by user journey, not features
- Write Procedures - Create step-by-step instructions with screenshots
- Add Context - Explain why and when, not just how
- Build Navigation - Create clear TOC, index, and search keywords
- Test Documentation - Validate against real user scenarios
Workflow 3: README Excellence
- Project Overview - One-paragraph description of what it does
- Installation - Clear setup instructions with prerequisites
- Quick Start - Minimal example to get running fast
- Usage Examples - Real-world code samples with explanations
- Configuration - Document all options, environment variables, flags
- Contributing - Guidelines for contributions and development setup
- License & Credits - Legal info and acknowledgments
Workflow 4: Architecture Documentation
- System Overview - High-level diagram and description
- Component Breakdown - Detail each major component and responsibility
- Data Flow - Document how information moves through system
- Deployment - Infrastructure, scaling, monitoring considerations
- Security Model - Authentication, authorization, data protection
- Decision Records - Document architectural decisions and rationale
Quick Reference
| Action | Command/Trigger |
|---|---|
| Create API docs | "Document this API" |
| Write README | "Create README for this project" |
| User guide | "Write user guide for [feature]" |
| Troubleshooting section | "Create troubleshooting guide" |
| Tutorial | "Write tutorial for [task]" |
| Release notes | "Generate release notes from changes" |
| Migration guide | "Write migration guide to [version]" |
| Code comments | "Document this code" |
Best Practices
- Start with why - Explain purpose and use cases before diving into details
- Show working examples - Every concept needs a concrete code sample
- Be consistent - Use same terminology, formatting, and structure throughout
- Write for scanning - Use headers, lists, tables, and code blocks liberally
- Test everything - Validate all code examples actually work
- Version clearly - Mark which version each feature/behavior applies to
- Update proactively - Keep docs in sync with code changes
- Link strategically - Connect related concepts without overwhelming
- Use diagrams - Complex flows need visual representation
- Maintain searchability - Optimize for ctrl+F and site search
- Provide context - Include when/why to use something, not just how
- Handle errors gracefully - Document common errors and solutions
- Write for internationalization - Use clear, simple language that translates well
- Include prerequisites - Never assume prior knowledge
- Offer quick wins - Give users success in under 5 minutes