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:
markdown
## 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