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)

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:

Search for actual implementation
Verify flags/arguments match
Check help text matches documentation
Validate examples are correct

Example check:

# 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.

2.0 KiB Raw Permalink Blame History