diegosouzapw Documentation Structure Validator
Validate documentation files for completeness, structure, and consistency.
Instructions
- Identify the documentation type (README, ADR, API docs, guide)
- Load the appropriate template from templates.md
- Check for required sections and common issues
- Review markdown syntax and formatting
- Generate a validation report with:
- ✅ Passed checks
- ⚠️ Warnings
- ❌ Critical issues
- 💡 Recommendations
Validation Checklist
README Files
- Title/project name present
- Description/purpose clear
- Installation instructions
- Usage examples
- Configuration section (if applicable)
- Contributing guidelines link
- License information
- Table of contents (for long READMEs)
- Badges (optional but recommended)
Architecture Decision Records (ADR)
- Title with number (ADR-###)
- Status (proposed/accepted/deprecated/superseded)
- Context section
- Decision section
- Consequences section
- Date
- References/links
API Documentation
- Endpoint descriptions
- Request/response examples
- Authentication details
- Error codes documentation
- Rate limiting info
- Versioning strategy
Common Issues
Refer to validation-rules.md for detailed rules and examples.
Usage Examples
Example 1: Validate README
User: "Check if the README is complete"
Claude: *reads README.md, compares against template, generates report*
Example 2: Validate ADR
User: "Validate the architecture decision docs in /docs/decisions/"
Claude: *validates each ADR file against ADR template*
Example 3: Batch validation
User: "Check all markdown files in /docs/"
Claude: *scans all .md files, validates each based on type*
Output Format
# Documentation Validation Report
**File**: path/to/file.md
**Type**: README
**Date**: YYYY-MM-DD
## Summary
- Total checks: 15
- Passed: 12 ✅
- Warnings: 2 ⚠️
- Critical: 1 ❌
## Critical Issues ❌
1. Missing installation instructions
## Warnings ⚠️
1. No contributing guidelines link
2. Code examples not syntax-highlighted
## Passed ✅
- Title present
- Description clear
- Usage examples included
...
## Recommendations 💡
1. Add badges for build status and license
2. Include table of contents for easier navigation
3. Add troubleshooting section
Tips
- For templates, see templates.md
- For validation rules, see validation-rules.md
- Always provide actionable feedback
- Prioritize critical issues over style preferences
- Link to examples when suggesting improvements