15 KiB
15 KiB
Operation: Full Documentation Validation
Execute comprehensive documentation validation workflow covering all documentation aspects.
Parameters from $ARGUMENTS
- path: Target plugin/marketplace path (required)
- detailed: Include detailed sub-reports (optional, default: true)
- fix-suggestions: Generate actionable improvement suggestions (optional, default: true)
- format: Output format (text|json|markdown) (optional, default: text)
Full Documentation Workflow
This operation orchestrates all documentation validation sub-operations to provide a complete documentation quality assessment.
Workflow
-
Initialize Validation Context
Create validation context: - Target path - Timestamp - Validation mode: comprehensive - Results storage structure Prepare for aggregating results from: - README validation - CHANGELOG validation - LICENSE validation - Examples validation -
Execute README Validation
Invoke: check-readme.md operation Parameters: - path: <target-path> - sections: default required sections - min-length: 500 Capture results: - README present: Boolean - Sections found: Array - Sections missing: Array - Length: Integer - Score: 0-100 - Issues: Array -
Execute CHANGELOG Validation
Invoke: validate-changelog.md operation Parameters: - file: CHANGELOG.md - format: keepachangelog - require-unreleased: true Capture results: - CHANGELOG present: Boolean - Format compliance: 0-100% - Version entries: Array - Issues: Array - Score: 0-100 -
Execute LICENSE Validation
Invoke: check-license.md operation Parameters: - path: <target-path> - check-consistency: true Capture results: - LICENSE present: Boolean - License type: String - OSI approved: Boolean - Consistent with manifest: Boolean - Issues: Array - Score: 0-100 -
Execute Examples Validation
Invoke: validate-examples.md operation Parameters: - path: <target-path> - no-placeholders: true - recursive: true Capture results: - Files checked: Integer - Examples found: Integer - Placeholders detected: Integer - Quality score: 0-100 - Issues: Array -
Aggregate Results
Calculate overall documentation score: weights = { readme: 40%, # Most important examples: 30%, # Critical for usability license: 20%, # Required for submission changelog: 10% # Recommended but not critical } overall_score = ( readme_score × 0.40 + examples_score × 0.30 + license_score × 0.20 + changelog_score × 0.10 ) Round to integer: 0-100 -
Categorize Issues by Priority
CRITICAL (P0 - Blocking): - README.md missing - LICENSE file missing - README < 200 characters - Non-OSI-approved license - License mismatch with manifest IMPORTANT (P1 - Should Fix): - README missing 2+ required sections - README < 500 characters - No examples in README - 5+ placeholder patterns - CHANGELOG has format errors RECOMMENDED (P2 - Nice to Have): - CHANGELOG missing - README missing optional sections - < 3 examples - Minor placeholder patterns -
Generate Improvement Roadmap
Create prioritized action plan: For each issue: - Identify impact on overall score - Estimate effort (Low/Medium/High) - Calculate score improvement - Generate specific remediation steps Sort by: Priority → Score Impact → Effort Example: 1. [P0] Add LICENSE file → +20 pts → 15 min 2. [P1] Expand README to 500+ chars → +10 pts → 30 min 3. [P1] Add 2 usage examples → +15 pts → 20 min 4. [P2] Create CHANGELOG.md → +10 pts → 15 min -
Determine Publication Readiness
Publication readiness determination: READY (90-100): - All critical requirements met - High-quality documentation - No blocking issues - Immediate submission recommended READY WITH MINOR IMPROVEMENTS (75-89): - Critical requirements met - Some recommended improvements - Can submit, but improvements increase quality - Suggested: Address P1 issues before submission NEEDS WORK (60-74): - Critical requirements met - Several important issues - Should address P1 issues before submission - Documentation needs expansion NOT READY (<60): - Critical issues present - Insufficient documentation quality - Must address P0 and P1 issues - Submission will be rejected -
Format Output
Based on format parameter: - text: Human-readable report - json: Structured JSON for automation - markdown: Formatted markdown report
Examples
# Full documentation validation with defaults
/documentation-validation full-docs path:.
# With detailed sub-reports
/documentation-validation full-docs path:. detailed:true
# JSON output for automation
/documentation-validation full-docs path:. format:json
# Without fix suggestions (faster)
/documentation-validation full-docs path:. fix-suggestions:false
# Validate specific plugin
/documentation-validation full-docs path:/path/to/plugin
Error Handling
Error: Multiple critical issues
❌ CRITICAL: Multiple blocking documentation issues
Documentation Score: <score>/100 ⚠️
BLOCKING ISSUES (<count>):
1. README.md not found
→ Create README.md with required sections
→ Minimum 500 characters
→ Include Overview, Installation, Usage, Examples, License
2. LICENSE file not found
→ Create LICENSE file with OSI-approved license
→ MIT License recommended
→ Must match plugin.json license field
3. License mismatch
→ plugin.json declares "Apache-2.0"
→ LICENSE file contains "MIT"
→ Update one to match the other
IMPORTANT ISSUES (<count>):
- README missing Examples section
- No code examples found
- CHANGELOG.md recommended
YOUR NEXT STEPS:
1. Add LICENSE file (CRITICAL - 15 minutes)
2. Create comprehensive README.md (CRITICAL - 30 minutes)
3. Add 3 usage examples (IMPORTANT - 20 minutes)
After addressing critical issues, revalidate with:
/documentation-validation full-docs path:.
Error: Documentation too sparse
⚠️ WARNING: Documentation exists but is too sparse
Documentation Score: 65/100 ⚠️
Your documentation meets minimum requirements but needs expansion
for professional quality.
AREAS NEEDING IMPROVEMENT:
1. README is only 342 characters (minimum: 500)
→ Expand installation instructions
→ Add more detailed usage examples
→ Include troubleshooting section
2. Only 1 example found (recommended: 3+)
→ Add basic usage example
→ Add advanced example
→ Add configuration example
3. CHANGELOG missing
→ Create CHANGELOG.md
→ Use Keep a Changelog format
→ Document version 1.0.0 features
IMPACT:
Current: 65/100 (Fair)
After improvements: ~85/100 (Good)
Time investment: ~45 minutes
Quality improvement: +20 points
Output Format
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
COMPREHENSIVE DOCUMENTATION VALIDATION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Target: <path>
Type: <marketplace|plugin>
Timestamp: <YYYY-MM-DD HH:MM:SS>
OVERALL DOCUMENTATION SCORE: <0-100>/100 <⭐⭐⭐⭐⭐>
Rating: <Excellent|Good|Fair|Needs Improvement|Poor>
Publication Ready: <Yes|Yes with improvements|Needs work|No>
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
COMPONENT SCORES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
README (Weight: 40%)
Score: <0-100>/100 ✅
Status: ✅ Complete and comprehensive
Sections: <N>/5 required sections found
Length: <N> characters (minimum: 500) ✅
Issues: None
EXAMPLES (Weight: 30%)
Score: <0-100>/100 ⚠️
Status: ⚠️ Could be improved
Examples found: <N> (recommended: 3+)
Placeholders: <N> detected
Issues: <N> placeholder patterns found
LICENSE (Weight: 20%)
Score: <0-100>/100 ✅
Status: ✅ Valid and consistent
Type: MIT License
OSI Approved: ✅ Yes
Consistency: ✅ Matches plugin.json
Issues: None
CHANGELOG (Weight: 10%)
Score: <0-100>/100 ⚠️
Status: ⚠️ Missing (recommended but not required)
Format: N/A
Versions: 0
Issues: CHANGELOG.md not found
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
ISSUES SUMMARY
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Critical (P0 - Blocking): <count>
Important (P1 - Should Fix): <count>
Recommended (P2 - Nice to Have): <count>
CRITICAL ISSUES:
[None - Ready for submission] ✅
IMPORTANT ISSUES:
⚠️ 1. Add 2 more usage examples to README
Impact: +15 points
Effort: Low (20 minutes)
⚠️ 2. Replace 3 placeholder patterns in examples
Impact: +10 points
Effort: Low (10 minutes)
RECOMMENDATIONS:
💡 1. Create CHANGELOG.md for version tracking
Impact: +10 points
Effort: Low (15 minutes)
💡 2. Add troubleshooting section to README
Impact: +5 points
Effort: Low (15 minutes)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
IMPROVEMENT ROADMAP
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Current Score: <score>/100
Target Score: 90/100 (Excellent - Publication Ready)
Gap: <gap> points
RECOMMENDED ACTIONS (to reach 90+):
1. [+15 pts] Add usage examples
Priority: High
Effort: 20 minutes
Description:
- Add 2 more concrete usage examples to README
- Include basic, intermediate, and advanced scenarios
- Use real plugin commands and parameters
2. [+10 pts] Clean up placeholder patterns
Priority: Medium
Effort: 10 minutes
Description:
- Replace "YOUR_VALUE" patterns with concrete examples
- Complete or remove TODO markers
- Use template syntax (${VAR}) for user-provided values
3. [+10 pts] Create CHANGELOG.md
Priority: Medium
Effort: 15 minutes
Description:
- Use Keep a Changelog format
- Document version 1.0.0 initial release
- Add [Unreleased] section for future changes
AFTER IMPROVEMENTS:
Projected Score: ~90/100 ⭐⭐⭐⭐⭐
Time Investment: ~45 minutes
Status: Excellent - Ready for submission
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PUBLICATION READINESS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Status: ✅ READY WITH MINOR IMPROVEMENTS
Your plugin documentation meets all critical requirements and is ready
for submission to OpenPlugins marketplace. The recommended improvements
above will increase quality score and provide better user experience.
✅ Strengths:
- Comprehensive README with all required sections
- Valid OSI-approved license (MIT)
- License consistent with plugin.json
- Good documentation structure
⚠️ Improvement Opportunities:
- Add more usage examples for better user onboarding
- Create CHANGELOG for version tracking
- Clean up minor placeholder patterns
NEXT STEPS:
1. (Optional) Address recommended improvements (~45 min)
2. Run validation again to verify improvements
3. Submit to OpenPlugins marketplace
Command to revalidate:
/documentation-validation full-docs path:.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Integration
This operation is the primary entry point for complete documentation validation:
Invoked by:
/documentation-validation full-docs path:.(direct invocation)/validation-orchestrator comprehensive path:.(as part of full plugin validation)- marketplace-validator agent (automatic documentation assessment)
Invokes sub-operations:
/documentation-validation readme path:./documentation-validation changelog file:CHANGELOG.md/documentation-validation license path:./documentation-validation examples path:.
Feeds results to:
/quality-analysis full-analysis(for overall quality scoring)/quality-analysis generate-report(for report generation)
JSON Output Format
When format:json is specified:
{
"validation_type": "full-documentation",
"target_path": "/path/to/plugin",
"timestamp": "2025-01-15T10:30:00Z",
"overall_score": 85,
"rating": "Good",
"publication_ready": "yes_with_improvements",
"components": {
"readme": {
"score": 90,
"status": "pass",
"present": true,
"sections_found": 5,
"sections_missing": 0,
"length": 1234,
"issues": []
},
"changelog": {
"score": 70,
"status": "warning",
"present": true,
"compliance": 70,
"issues": ["Invalid version header format"]
},
"license": {
"score": 100,
"status": "pass",
"present": true,
"type": "MIT",
"osi_approved": true,
"consistent": true,
"issues": []
},
"examples": {
"score": 75,
"status": "warning",
"examples_found": 2,
"placeholders_detected": 3,
"issues": ["Placeholder patterns detected"]
}
},
"issues": {
"critical": [],
"important": [
{
"component": "examples",
"message": "Add 2 more usage examples",
"impact": 15,
"effort": "low"
}
],
"recommended": [
{
"component": "readme",
"message": "Add troubleshooting section",
"impact": 5,
"effort": "low"
}
]
},
"improvement_roadmap": [
{
"action": "Add usage examples",
"points": 15,
"priority": "high",
"effort": "20 minutes"
}
],
"projected_score_after_improvements": 95
}
Request: $ARGUMENTS