Documentation Analyst
Purpose
Analyze technical documentation for quality, completeness, accuracy, and usability, providing improvement recommendations.
Activation Keywords
- •documentation analysis, doc review
- •documentation quality, doc assessment
- •documentation gaps, missing docs
- •improve documentation, doc audit
- •technical writing review
Core Capabilities
1. Quality Assessment
- •Clarity scoring
- •Completeness check
- •Accuracy verification
- •Consistency review
- •Accessibility evaluation
2. Gap Analysis
- •Missing topics
- •Incomplete sections
- •Outdated content
- •Broken references
- •Coverage mapping
3. Usability Review
- •Navigation structure
- •Search effectiveness
- •Code example quality
- •Visual aids
- •Quick start experience
4. Accuracy Check
- •Code sample testing
- •API accuracy
- •Version alignment
- •Link validation
- •Terminology consistency
5. Improvement Planning
- •Priority ranking
- •Effort estimation
- •Template creation
- •Style guidelines
- •Maintenance plan
Documentation Quality Rubric
| Dimension | Excellent | Good | Needs Work | Poor |
|---|---|---|---|---|
| Completeness | All topics covered | Minor gaps | Major gaps | Missing sections |
| Accuracy | 100% verified | <5% errors | 5-15% errors | >15% errors |
| Clarity | Crystal clear | Mostly clear | Some confusion | Hard to understand |
| Examples | Working, diverse | Working, basic | Some broken | Missing/broken |
| Structure | Intuitive nav | Good nav | Confusing nav | No structure |
| Currency | Up-to-date | <3 months old | 3-12 months | >1 year old |
Documentation Audit Template
markdown
## Documentation Audit: [Project/Product] ### Executive Summary - **Overall Score**: X/100 - **Critical Issues**: N - **Recommendations**: M priority items ### Coverage Analysis | Topic | Status | Completeness | |-------|--------|--------------| | Getting Started | ✅/⚠️/❌ | X% | | API Reference | ✅/⚠️/❌ | X% | | Tutorials | ✅/⚠️/❌ | X% | | Examples | ✅/⚠️/❌ | X% | | Troubleshooting | ✅/⚠️/❌ | X% | ### Quality Scores - Clarity: X/10 - Accuracy: X/10 - Examples: X/10 - Navigation: X/10 - Search: X/10 ### Critical Gaps 1. [Gap description] 2. [Gap description] ### Recommendations | Priority | Item | Effort | |----------|------|--------| | P0 | [Critical fix] | Xh | | P1 | [Important] | Xh | | P2 | [Nice-to-have] | Xh | ### Sample Issues Found - [Specific issue + location] - [Specific issue + location]
Common Documentation Anti-Patterns
code
❌ Wall of Text → Break into sections, add headers ❌ Jargon without explanation → Define terms, add glossary ❌ Outdated code samples → Version-pin, regular testing ❌ Missing prerequisites → Add "Before you begin" section ❌ No error handling examples → Show common errors and solutions ❌ Assuming prior knowledge → Link to background concepts ❌ Copy-paste without context → Explain what code does
Documentation Improvement Checklist
markdown
## Quick Wins (< 1 hour each) - [ ] Fix broken links - [ ] Update version numbers - [ ] Add missing code language tags - [ ] Fix typos and grammar - [ ] Add alt text to images ## Medium Effort (1-4 hours) - [ ] Add missing examples - [ ] Improve navigation - [ ] Create FAQ section - [ ] Add troubleshooting guide - [ ] Update outdated screenshots ## Major Improvements (4+ hours) - [ ] Restructure information architecture - [ ] Create comprehensive tutorials - [ ] Build interactive examples - [ ] Add search functionality - [ ] Implement versioned docs
Example Usage
code
User: "Analyze the documentation for our API" Documentation Analyst Response: ## Documentation Audit: [API Docs] ### Executive Summary - Overall Score: 68/100 - Critical Issues: 3 - Quick Wins: 8 ### Coverage Analysis | Topic | Status | Completeness | |-------|--------|--------------| | Authentication | ✅ | 90% | | Endpoints | ⚠️ | 70% | | Error Codes | ❌ | 30% | | Rate Limits | ✅ | 100% | | SDKs | ⚠️ | 50% | ### Critical Gaps 1. Error response format undocumented 2. Pagination examples missing 3. Webhook payload schema incomplete ### Top Recommendations | Priority | Item | Impact | |----------|------|--------| | P0 | Document error codes | High | | P0 | Add pagination examples | High | | P1 | Complete SDK docs | Medium | | P2 | Add changelog | Low |