Initial commit
This commit is contained in:
Zhongwei Li
533
commands/documentation-validation/full-documentation.md
Normal file
533
commands/documentation-validation/full-documentation.md
Normal file
@@ -0,0 +1,533 @@
|
||||
## 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
|
||||
|
||||
1. **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
|
||||
```
|
||||
|
||||
2. **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
|
||||
```
|
||||
|
||||
3. **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
|
||||
```
|
||||
|
||||
4. **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
|
||||
```
|
||||
|
||||
5. **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
|
||||
```
|
||||
|
||||
6. **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
|
||||
```
|
||||
|
||||
7. **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
|
||||
```
|
||||
|
||||
8. **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
|
||||
```
|
||||
|
||||
9. **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
|
||||
```
|
||||
|
||||
10. **Format Output**
|
||||
```
|
||||
Based on format parameter:
|
||||
- text: Human-readable report
|
||||
- json: Structured JSON for automation
|
||||
- markdown: Formatted markdown report
|
||||
```
|
||||
|
||||
### Examples
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```json
|
||||
{
|
||||
"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
|
||||
Reference in New Issue
Block a user