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
1---2name: technical-writer3description: Create clear, accurate technical documentation for developers and end users4---56# Technical Writer78Transform 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.910Whether 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.1112Ideal 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.1314## Core Workflows1516### Workflow 1: API Documentation171. **Analyze Codebase** - Review API endpoints, parameters, responses182. **Structure Reference** - Organize by resource/endpoint with consistent formatting193. **Document Endpoints** - Write clear descriptions, parameters, request/response examples204. **Add Code Samples** - Include examples in multiple languages215. **Create Quick Start** - Write getting-started guide with authentication226. **Build Error Reference** - Document error codes and troubleshooting237. **Generate OpenAPI Spec** - Create machine-readable API specification2425### Workflow 2: User Guide Creation261. **Audience Analysis** - Identify user personas and skill levels272. **Task Mapping** - List all user tasks and workflows283. **Content Outline** - Structure guide by user journey, not features294. **Write Procedures** - Create step-by-step instructions with screenshots305. **Add Context** - Explain why and when, not just how316. **Build Navigation** - Create clear TOC, index, and search keywords327. **Test Documentation** - Validate against real user scenarios3334### Workflow 3: README Excellence351. **Project Overview** - One-paragraph description of what it does362. **Installation** - Clear setup instructions with prerequisites373. **Quick Start** - Minimal example to get running fast384. **Usage Examples** - Real-world code samples with explanations395. **Configuration** - Document all options, environment variables, flags406. **Contributing** - Guidelines for contributions and development setup417. **License & Credits** - Legal info and acknowledgments4243### Workflow 4: Architecture Documentation441. **System Overview** - High-level diagram and description452. **Component Breakdown** - Detail each major component and responsibility463. **Data Flow** - Document how information moves through system474. **Deployment** - Infrastructure, scaling, monitoring considerations485. **Security Model** - Authentication, authorization, data protection496. **Decision Records** - Document architectural decisions and rationale5051## Quick Reference5253| Action | Command/Trigger |54|--------|-----------------|55| Create API docs | "Document this API" |56| Write README | "Create README for this project" |57| User guide | "Write user guide for [feature]" |58| Troubleshooting section | "Create troubleshooting guide" |59| Tutorial | "Write tutorial for [task]" |60| Release notes | "Generate release notes from changes" |61| Migration guide | "Write migration guide to [version]" |62| Code comments | "Document this code" |6364## Best Practices6566- **Start with why** - Explain purpose and use cases before diving into details67- **Show working examples** - Every concept needs a concrete code sample68- **Be consistent** - Use same terminology, formatting, and structure throughout69- **Write for scanning** - Use headers, lists, tables, and code blocks liberally70- **Test everything** - Validate all code examples actually work71- **Version clearly** - Mark which version each feature/behavior applies to72- **Update proactively** - Keep docs in sync with code changes73- **Link strategically** - Connect related concepts without overwhelming74- **Use diagrams** - Complex flows need visual representation75- **Maintain searchability** - Optimize for ctrl+F and site search76- **Provide context** - Include when/why to use something, not just how77- **Handle errors gracefully** - Document common errors and solutions78- **Write for internationalization** - Use clear, simple language that translates well79- **Include prerequisites** - Never assume prior knowledge80- **Offer quick wins** - Give users success in under 5 minutes
jmsktm