| description | Review and improve documentation for novice users with technical writing best practices |
|---|
Review documentation files from a professional technical writer's perspective, focusing on novice user experience.
For each document, evaluate:
- Does it explain concepts before using them?
- Does it avoid jargon, or explain it when necessary?
- Are examples concrete and realistic?
- Does it explain what something is before how to use it?
- Are prerequisites clearly stated?
- Are there quick start examples?
- Are edge cases and errors addressed?
- Are commands copy-paste ready?
- Is expected output shown?
- Are "when to use" hints provided?
- Do links to related docs exist?
- Does the order make sense for newcomers?
- Are sections clearly separated?
- Is there a logical flow from simple to complex?
For each document, provide:
## [Document Name]
| Aspect | Rating (1-5) | Notes |
|--------|--------------|-------|
| Clarity | ⭐⭐⭐ | ... |
| Completeness | ⭐⭐ | ... |
| Actionability | ⭐⭐⭐⭐ | ... |
| Structure | ⭐⭐⭐ | ... |
**Issues:**
1. Issue description
2. Issue description
**Suggested Fixes:**
- Fix description| Issue | Fix |
|---|---|
| Missing intro | Add opening paragraph explaining what and why |
| No prerequisites | Add prerequisites section with requirements |
| Jargon without explanation | Add callout boxes explaining terminology |
| No examples | Add Quick Start or example sections |
| Flat structure | Organize into logical sections |
| No cross-references | Add "Next Steps" or "See Also" links |
| Terminal vs editor confusion | Clarify which commands run where |
- Read the document from start to finish as a novice would
- Rate each aspect using the criteria above
- Identify specific issues with line references
- Suggest concrete fixes with example text
- Prioritize fixes as High/Medium/Low impact
- High: Blocks novice users from succeeding
- Medium: Causes confusion but users can figure it out
- Low: Nice to have improvements