86 lines
2.0 KiB
Markdown
86 lines
2.0 KiB
Markdown
# Documentation Validator Reference
|
|
|
|
Detailed validation rules and patterns for documentation quality assurance.
|
|
|
|
## Markdown Linting Rules
|
|
|
|
### Headings
|
|
- Must start with `#` (H1) for document title
|
|
- No skipping heading levels (no H1 → H3)
|
|
- Each heading should be unique
|
|
- Use sentence case for headings
|
|
|
|
### Code Blocks
|
|
- Always specify language: ` ```bash `, ` ```python `, etc.
|
|
- Code should be runnable (or marked as pseudocode)
|
|
- Avoid long lines (max 80-100 characters)
|
|
|
|
### Links
|
|
- Use relative links for internal files
|
|
- Check external links are accessible
|
|
- Use descriptive link text (not "click here")
|
|
|
|
### Lists
|
|
- Consistent marker style (- vs * vs +)
|
|
- Proper indentation for nested lists
|
|
- Complete sentences with periods
|
|
|
|
## Version Validation
|
|
|
|
Check version consistency across:
|
|
- package.json (`version` field)
|
|
- pyproject.toml (`version` field)
|
|
- README.md (version badges, installation commands)
|
|
- CHANGELOG.md (latest version entry)
|
|
- setup.py (`version` field)
|
|
|
|
## CLI Command Validation
|
|
|
|
For each command mentioned in docs:
|
|
1. Search for actual implementation
|
|
2. Verify flags/arguments match
|
|
3. Check help text matches documentation
|
|
4. Validate examples are correct
|
|
|
|
Example check:
|
|
```bash
|
|
# Documentation says:
|
|
make install MODULE=foo
|
|
|
|
# Verify:
|
|
grep -r "CLAUDE_DIR" Makefile # Check parameter exists
|
|
make help # Verify command listed
|
|
```
|
|
|
|
## Common Issues
|
|
|
|
### Missing Installation Steps
|
|
- No prerequisites listed
|
|
- No dependency installation
|
|
- Missing system requirements
|
|
- No version requirements
|
|
|
|
### Broken Examples
|
|
- Code examples with syntax errors
|
|
- Commands that don't exist
|
|
- File paths that don't exist
|
|
- Outdated package names
|
|
|
|
### Inconsistent Terminology
|
|
- "repo" vs "repository"
|
|
- "module" vs "package"
|
|
- "CLI" vs "command-line tool"
|
|
|
|
Pick one term and use it throughout.
|
|
|
|
## Auto-Fix Patterns
|
|
|
|
Some issues can be auto-fixed:
|
|
- Add missing code block language hints
|
|
- Fix heading hierarchy
|
|
- Normalize list markers
|
|
- Add table of contents
|
|
- Update version numbers
|
|
|
|
Ask user before applying fixes.
|