6.2 KiB
Documentation Standards
Comprehensive Requirements for Claude Code Skills Documentation (2024-2025)
Last Updated: {{DATE}}
Quick Reference (82 Requirements)
Legend: 🔴 Critical | 🟡 Important | 🟢 Desired | ⚠️ Conditional | ✅ Already implemented
| Category | Count | 🔴 | 🟡 | 🟢 | ⚠️ | ✅ | Validator |
|---|---|---|---|---|---|---|---|
| Core Documentation | 25 | 8 | 12 | 5 | 0 | 0 | ln-121, ln-122 |
| Claude Code Integration | 5 | 1 | 2 | 2 | 0 | 0 | ln-121 v2.1.0+ |
| AI-Friendly Writing | 6 | 0 | 5 | 1 | 0 | 0 | ln-121 warning |
| Markdown Best Practices | 6 | 0 | 4 | 2 | 0 | 0 | ln-121 v2.1.0+ |
| Code Examples Quality | 5 | 1 | 2 | 2 | 0 | 0 | Manual + CI |
| DIATAXIS Framework | 5 | 0 | 1 | 2 | 0 | 2 | Manual |
| Project Files | 6 | 1 | 3 | 2 | 0 | 0 | Manual |
| Quality Checks | 5 | 0 | 4 | 1 | 0 | 0 | markdownlint, Vale |
| Front Matter (SSG) | 3 | 0 | 0 | 2 | 1 | 0 | Conditional |
| Visual Documentation | 5 | 0 | 0 | 4 | 0 | 1 | Manual |
| Conventional Commits | 4 | 0 | 1 | 1 | 0 | 2 | commitlint |
| Security & Compliance | 4 | 1 | 3 | 0 | 0 | 0 | Manual |
| Performance | 3 | 0 | 1 | 2 | 0 | 0 | Manual |
Total: 82 requirements | 🔴 12 Critical | 🟡 38 Important | 🟢 24 Desired | ⚠️ 1 Conditional | ✅ 5 Implemented
Key Requirements by Priority
Critical (Must Have)
| Requirement | Rationale | Validator |
|---|---|---|
| CLAUDE.md ≤100 lines | Claude Code performance optimization | ln-121 v2.1.0+ |
| All code examples runnable | Prevent documentation drift | Manual + CI |
| LICENSE file exists | Legal compliance | Manual |
| Never commit secrets | Security breach prevention | Manual |
Important (Should Have)
Claude Code Integration:
- @-sourcing support in CLAUDE.md (DRY pattern)
- Explicitly specify
setting_sources=["project"]
AI-Friendly Writing:
- Use second person ("you" vs "users")
- Active voice instead of passive
- Short sentences (max 25 words)
- Prohibited phrases ("please note", "simply", "just", "easily")
- Don't assume prior knowledge
Markdown Best Practices:
- Header depth ≤ h3 (rarely h4)
- Descriptive links (not "click here")
- Callouts/Admonitions for important info
- Files end with single blank line (POSIX)
Code Examples Quality:
- Test documentation examples in CI/CD
- Include setup context (directory, prerequisites)
Project Files:
- CONTRIBUTING.md (contribution process)
- SECURITY.md (vulnerability reporting)
- .gitignore for docs (exclude generated files)
Quality Checks:
- markdownlint-cli2 (.markdownlint.jsonc)
- Vale.sh (.vale.ini for editorial checks)
- Build verification (prevent broken deployments)
- Link checking (dead link detection)
Security & Compliance:
- GitHub Secrets for CI/CD
- .env.example instead of .env
- Vulnerability reporting process (SECURITY.md)
Performance:
- Optimize CLAUDE.md size (-30 to -40% tokens via @-sourcing)
Desired (Nice to Have)
Documentation Structure: DIATAXIS framework (Tutorial/How-to/Reference/Explanation sections), How-to guides ✅, Reference docs ✅
Visual Elements: Mermaid diagrams ✅, workflow diagrams, sequence diagrams, light/dark theme support, centralized image storage
Version Control: Conventional Commits format, auto-generate CHANGELOG, Keep a Changelog ✅, Semantic versioning ✅
Code Quality: Realistic variable names (not foo/bar), show expected output, code blocks in step lists
Project Files: CODE_OF_CONDUCT.md, README badges, vocabulary files for terminology
Advanced Features: SessionStart hooks, subagents in .claude/agents/*.md, Front Matter for SSG (Hugo/Docusaurus) ⚠️, lazy loading, caching strategy
Writing Style: Avoid first-person pronouns, Title case for h1/Sentence case for h2+
Standards Compliance
| Standard | Reference |
|---|---|
| ISO/IEC/IEEE 29148:2018 | Requirements Engineering |
| ISO/IEC/IEEE 42010:2022 | Architecture Description |
| DIATAXIS Framework | diataxis.fr - Documentation structure |
| RFC 2119, WCAG 2.1 AA | Requirement keywords, Accessibility |
| OWASP Top 10 | Security requirements |
| Conventional Commits | conventionalcommits.org |
| Keep a Changelog | Changelog format |
| Semantic Versioning | Major.Minor.Patch |
Sources: Claude Code docs, Clever Cloud guide, DIATAXIS framework, Matter style guide
Verification Checklist
Before submitting documentation:
- CLAUDE.md ≤100 lines - Concise and focused
- All code examples runnable - No placeholders, tested
- LICENSE file exists - Legal compliance
- No secrets committed - API keys in .env only
- Header depth ≤ h3, files end with blank line - Markdown standards
- Active voice, second person, short sentences - AI-friendly writing
- SCOPE tag in docs/, Maintenance section** - Core requirements
- Descriptive links, callouts for important info - Best practices
Maintenance
Update Triggers:
- When Claude Code releases new best practices
- When industry standards evolve (ISO/IEC/IEEE updates)
- When new validation tools become available
- When ln-121-structure-validator or ln-122-content-updater add new checks
- Annual review (Q1 each year)
Verification:
- All 82 requirements documented with rationale
- Priority levels assigned (Critical/Important/Desired)
- Validators identified for automated checks
- Standards compliance table complete
- References link to authoritative sources
- Verification checklist covers all critical requirements
Last Updated: {{DATE}}
Template Version: 2.0.0 (MAJOR: Progressive Disclosure - reduced from 390→160 lines (-59%), removed detailed sections 1-12 and Implementation Roadmap, converted to compact table format, added SCOPE tag) Template Last Updated: {{DATE}}