1.5 KiB
1.5 KiB
name, description, category, required_tools
| name | description | category | required_tools | |||
|---|---|---|---|---|---|---|
| Technical Writing | Create clear, accessible documentation for technical and non-technical audiences with practical examples and logical structure | documentation |
|
Technical Writing
Purpose
Create clear, accurate documentation that helps users understand and use software effectively, regardless of their technical background.
When to Use
- Writing user guides and tutorials
- Creating README files
- Documenting features
- Explaining complex concepts
Key Capabilities
- Clarity - Write simple, jargon-free explanations
- Structure - Organize information logically
- Examples - Provide practical, working examples
Approach
- Know your audience (developers vs end-users)
- Start with the "why" before the "how"
- Use clear headings and sections
- Provide concrete examples
- Include troubleshooting for common issues
Example
Bad: "The API utilizes RESTful paradigms for CRUD operations"
Good:
## Creating a Task
To create a new task, send a POST request:
```bash
POST /api/tasks
{
"title": "Fix login bug",
"priority": "high"
}
```
The API returns the created task with an ID you can use to track progress.
Best Practices
- ✅ Use active voice ("Click the button" not "The button should be clicked")
- ✅ Include working code examples
- ✅ Explain error messages users might see
- ❌ Avoid: Assuming prior knowledge without explanation