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

Documentation Audit Template

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

❌ 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

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

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 |