Diataxis Documentation Framework
Audit, classify, validate, and scaffold documentation using the Diataxis framework.
Quick Start
# Classify individual files
uv run scripts/diataxis_classify.py docs/*.md
# Audit a docs directory for coverage
uv run scripts/diataxis_audit.py --dir docs
# Validate quadrant purity
uv run scripts/diataxis_validate.py --dir docs
# Scaffold a new Diataxis structure
uv run scripts/diataxis_scaffold.py --dry-run
uv run scripts/diataxis_scaffold.py
Capabilities
| Script | Purpose | Key Flags |
|---|---|---|
diataxis_classify.py | Classify files into quadrants | --json, --verbose, --no-content |
diataxis_audit.py | Coverage report with quality score | --dir, --json, --min-coverage |
diataxis_validate.py | Lint for quadrant purity (DX001-DX010) | --dir, --file, --strict, --json |
diataxis_scaffold.py | Generate folder structure | --layout folders|flat, --init-config, --dry-run |
The Four Quadrants
| Quadrant | Orientation | User State | Folder |
|---|---|---|---|
| Tutorial | Learning | Study + Action | tutorials/ |
| How-to | Task | Work + Action | how-to/ |
| Reference | Information | Work + Cognition | reference/ |
| Explanation | Understanding | Study + Cognition | explanation/ |
Classification Algorithm
Multi-signal weighted scoring (title 30%, headings 25%, content 25%, structure 20%). Documents scoring highly for 2+ quadrants are flagged as "collapsed" with split suggestions.
Validation Rules
| ID | Rule | Severity |
|---|---|---|
| DX001 | Tutorial contains reference tables | warning |
| DX002 | How-to has long conceptual preamble | warning |
| DX003 | Reference contains step-by-step instructions | warning |
| DX004 | Explanation contains execution commands | warning |
| DX005 | No clear quadrant signal | info |
| DX006 | Collapsed document (mixed quadrants) | warning |
| DX007 | Tutorial missing prerequisites | info |
| DX008 | Tutorial missing learning objectives | info |
| DX009 | How-to missing problem statement | info |
| DX010 | Reference missing tables | info |
Config File (.diataxis-config.json)
Optional per-project override:
{
"version": 1,
"root": "docs",
"layout": "folders",
"ignore": ["node_modules", ".git", "adr", "rfcs", "*.pdf"],
"custom_signals": {}
}
Create with uv run scripts/diataxis_scaffold.py --init-config.
Common Issues
| Issue | Fix |
|---|---|
uv not found | curl -LsSf https://astral.sh/uv/install.sh | sh or run with python3 scripts/diataxis_classify.py |
| Low confidence on all files | Files may lack quadrant-specific keywords; use --verbose to inspect scores |
| Too many collapsed warnings | Some docs legitimately mix quadrants; consider splitting or accepting |
See TROUBLESHOOTING.md for all error scenarios.
References
- WORKFLOW.md — Full methodology (discover, classify, audit, validate, scaffold)
- EXAMPLES.md — Real-world examples for all operations
- TROUBLESHOOTING.md — Error handling and debugging tips
- Diataxis framework — Official documentation