documentation-quality-checklist

# Documentation Quality Checklist Validation criteria for generated documentation pages. Run through this checklist before writing any page to disk. ## Content Completeness - [ ] All required sections are present - [ ] All required diagrams are generated and embedded - [ ] No TODO or placeholder text remains - [ ] Introduction provides context and purpose - [ ] Conclusion summarizes key points ## Evidence Backing - [ ] Every major claim cites a source - [ ] Code examples are real (from codebase, not invented) - [ ] File references use correct paths - [ ] Line numbers are accurate - [ ] Evidence sources are listed in metadata ## Markdown Syntax - [ ] Headings have proper hierarchy (h1 → h2 → h3) - [ ] Code blocks include language specification - [ ] Tables are properly formatted - [ ] Lists use consistent formatting - [ ] No broken markdown syntax ## Diagram Validation - [ ] ASCII diagrams render correctly in monospace - [ ] Diagram has descriptive title - [ ] Diagram has explanatory caption - [ ] Diagram content matches surrounding text - [ ] Box widths are consistent ## Cross-References - [ ] Internal links use relative paths: `[text](../../path/to/page.md)` - [ ] Referenced pages exist in sitemap - [ ] External links are properly formatted - [ ] Bidirectional references where appropriate - [ ] Breadcrumb navigation included if appropriate ## Word Count Guidelines | Page Type | Target Range | Notes | |-----------|--------------|-------| | Overview pages | 500-1000 | Concise, high-level | | Architecture pages | 1000-2000 | Detailed with diagrams | | Component/service pages | 800-1500 | Focused on single topic | | Workflow pages | 600-1200 | Step-by-step with diagrams | | Reference pages | 300-800 | Tables and lists | ## Quick Validation For rapid checks, verify these critical items: 1. **Required content exists** - All sections and diagrams present 2. **Evidence is real** - Code examples from actual codebase 3. **Links work** - Cross-references match sitemap 4. **Renders correctly** - Markdown syntax is valid ## Failure Criteria A page should NOT be written if: - Missing more than one required section - No evidence sources cited - Contains placeholder text (TODO, TBD, etc.) - Markdown has syntax errors that break rendering - Word count is below minimum for page type --- **Version:** 1.0 **Last Updated:** 2026-01-22