| name | adhd-friendly-documentation |
| description | Create documentation optimized for ADHD and neurodivergent readers with short scannable content, clear hierarchy, progressive disclosure, actionable steps, and reduced cognitive load. Use when creating or improving any technical documentation (README files, API docs, tutorials, guides, onboarding materials) or when users request accessible, easy-to-scan, or beginner-friendly documentation. |
ADHD-Friendly Documentation
Overview
This skill transforms technical documentation into accessible, scannable content optimized for ADHD and neurodivergent readers. Apply ADHD-friendly principles to create documentation that reduces cognitive load, improves information retention, and enables quick scanning while maintaining technical accuracy.
Core principles:
- Short, scannable content with clear visual hierarchy
- Progressive disclosure of complexity
- Actionable steps with concrete examples
- Visual aids and consistent formatting
- Quick reference sections for rapid lookup
When to Use This Skill
Use this skill when:
- Creating new documentation (READMEs, guides, tutorials, API docs)
- Improving existing documentation for accessibility
- Users request "easy to understand," "beginner-friendly," or "scannable" docs
- Writing onboarding materials or getting-started guides
- Documenting complex systems that need clear explanation
- Creating internal documentation or knowledge bases
Always apply these principles to documentation unless the user explicitly requests a different style.
Creating ADHD-Friendly Documentation
Step 1: Choose the Right Template
Select the appropriate template from assets/ based on documentation type:
Quick Start / README → assets/template-quick-start.md
- Project introductions
- Getting started guides
- Repository README files
- Installation instructions
API Documentation → assets/template-api-docs.md
- Method/function reference
- Library documentation
- REST/GraphQL API docs
- SDK documentation
Tutorials → assets/template-tutorial.md
- Step-by-step guides
- Learning paths
- Hands-on workshops
- Feature walkthroughs
Step 2: Apply Core Patterns
Reference references/adhd-patterns.md for detailed guidance on:
Visual Hierarchy:
- Use clear H1/H2/H3 structure (max 3-4 levels deep)
- Add generous whitespace between sections
- Keep header nesting shallow for easy scanning
Scannable Content:
- Lead with key information (what/why in first 2-3 lines)
- Use bullet points over paragraphs
- Limit paragraphs to 2-3 sentences maximum
- Bold important terms and actions
- Use
code formatting for technical terms
Progressive Disclosure:
- Start with TL;DR or Quick Start section
- Provide quick wins before deep explanations
- Link to details rather than including inline
- Separate basic from advanced content
Action-Oriented:
- Start instructions with verbs (Install, Run, Create, Configure)
- Number sequential steps clearly
- Include expected outcomes after each step
- Provide complete, runnable code examples
Cognitive Load Reduction:
- One concept per section
- Use consistent terminology throughout
- Define jargon on first use
- Include time estimates for tutorials
- Explain "why" for non-obvious steps
Step 3: Add Visual Elements
Enhance scannability with:
Tables for comparisons and structured data:
| Feature | Option A | Option B |
|---------|----------|----------|
| Speed | Fast | Slow |
Callouts for important information:
> ⚠️ **Warning:** Critical information
> 💡 **Tip:** Helpful suggestion
> ℹ️ **Note:** Additional context
> ✅ **Success:** Expected outcome
Code blocks with syntax highlighting:
```language
// Complete, runnable example
// Comments for non-obvious parts
```
Checklists for learning objectives:
- [ ] Objective 1
- [ ] Objective 2
Step 4: Structure for Scanning
Organize information for quick navigation:
Information hierarchy:
- Title + one-line summary
- Quick start (< 2 minutes)
- Core concepts (5-10 min)
- Tutorials/guides (hands-on)
- API reference (lookup)
- Advanced topics (deep dives)
Section format:
- Lead with the most important info
- Keep sections focused (one topic each)
- Use consistent formatting patterns
- Provide clear navigation (table of contents, next steps)
Step 5: Validate with Checklist
Use references/checklist.md to validate documentation quality:
Quick validation checks:
- ✅ Clear headers and structure
- ✅ Paragraphs under 3 sentences
- ✅ Sequential steps numbered
- ✅ Code examples complete and runnable
- ✅ Key terms bolded
- ✅ One concept per section
Priority fixes if time is limited:
- Add clear headers
- Break up long paragraphs
- Add quick start section
- Number sequential steps
- Bold key terms
See the complete checklist in references/checklist.md for comprehensive validation.
Anti-Patterns to Avoid
Reference references/adhd-patterns.md for detailed anti-patterns. Key ones:
❌ Walls of text - No paragraphs over 5 sentences
- Instead: Break into bullet points or shorter paragraphs
❌ Hidden action steps - Don't bury commands in prose
- Instead: Use numbered lists with explicit actions
❌ Ambiguous language - Avoid "might," "could," "sometimes"
- Instead: Provide clear guidance on when to use what
❌ Missing expected outcomes - Always show what should happen
- Instead: Add "You should see:" after steps
❌ Undefined jargon - Define technical terms on first use
- Instead: Explain or link to definitions
Working with Existing Documentation
When improving existing docs:
- Assess current state - Identify walls of text, missing structure, buried actions
- Add quick wins first - Quick start section, clear headers, numbered steps
- Break up content - Convert paragraphs to bullets, add whitespace
- Add visual hierarchy - Ensure proper header levels and structure
- Validate - Use checklist from
references/checklist.md
Preserve technical accuracy while improving accessibility.
Resources
references/adhd-patterns.md
Comprehensive guide to ADHD-friendly documentation patterns including:
- Core principles and detailed explanations
- Specific patterns for different doc types (Quick Start, API, Tutorial, Troubleshooting)
- Visual aids guidelines (tables, callouts, diagrams)
- Anti-patterns with before/after examples
- Formatting conventions
- Content organization strategies
- Writing style guidelines
- Accessibility considerations
Use this as the primary reference for detailed pattern guidance.
references/checklist.md
Quick validation checklist with:
- Structure & hierarchy checks
- Scannability criteria
- Progressive disclosure validation
- Action steps quality
- Cognitive load assessment
- Visual elements checklist
- Common anti-patterns to avoid
- Quick validation tests (Skim Test, 30-Second Test)
- Scoring system
Use this to validate documentation before publishing.
assets/template-quick-start.md
Template for README files and getting-started guides with:
- Quick start section (60 seconds)
- What this does explanation
- Common use cases
- Next steps navigation
- Quick reference
- Troubleshooting section
Use when creating project READMEs or quick-start guides.
assets/template-api-docs.md
Template for API and library documentation with:
- Method documentation format
- Parameter tables
- Common examples
- Error handling
- Rate limiting and pagination
- Complete working examples
Use when documenting APIs, libraries, or SDKs.
assets/template-tutorial.md
Template for step-by-step tutorials with:
- Learning objectives
- Step-by-step instructions with checkpoints
- Common issues sections
- "You're done" celebration
- Next steps and extensions
- Complete code sections
Use when creating hands-on tutorials or walkthroughs.
Best Practices
Start simple:
- Begin with template that matches doc type
- Focus on quick wins (headers, bullets, quick start)
- Add complexity progressively
Be consistent:
- Use same formatting patterns throughout
- Maintain consistent terminology
- Follow established conventions in templates
Test scannability:
- Can readers find what they need in 30 seconds?
- Are headers descriptive and hierarchical?
- Can someone skim bullets and understand the content?
Prioritize action:
- Make it easy to get started quickly
- Provide working examples early
- Show expected results
Reduce friction:
- Remove barriers to understanding
- Explain non-obvious steps
- Provide multiple entry points (quick start, deep dive, reference)
Writing Style
Use imperative/infinitive form throughout:
- ✅ "Install the package using npm"
- ✅ "To configure authentication, create a config file"
- ❌ "You should install the package"
- ❌ "If you want to configure authentication, you can create..."
Voice:
- Present tense, active voice
- Direct and conversational but precise
- Command form for instructions
Sentence structure:
- Lead with action or key point
- Keep under 20 words
- One idea per sentence
Examples
Example 1: README Documentation
User asks: "Create a README for my authentication library"
Approach:
- Start with
assets/template-quick-start.md
- Add one-line description of auth library
- Create 60-second quick start (install, configure, use)
- Show 2-3 common use cases with code
- Add API reference links
- Include troubleshooting for common auth issues
- Validate with
references/checklist.md
Example 2: API Documentation
User asks: "Document my REST API endpoints"
Approach:
- Use
assets/template-api-docs.md structure
- For each endpoint: What it does, when to use, quick example
- Add parameter tables with types and descriptions
- Include authentication section
- Show error responses and handling
- Add rate limiting information
- Provide complete working examples
Example 3: Tutorial
User asks: "Write a getting started guide for building a todo app"
Approach:
- Start with
assets/template-tutorial.md
- Define learning objectives and time estimate
- Break into clear steps (Setup → Add todos → Display → Complete)
- Each step: Goal, instructions, checkpoint, expected result
- Add "What you learned" summaries
- Include troubleshooting section
- Suggest next steps and extensions
Example 4: Improving Existing Docs
User asks: "Make this documentation easier to understand"
Approach:
- Read existing documentation
- Identify issues (walls of text, missing structure, unclear actions)
- Add quick start section if missing
- Break paragraphs into bullets
- Add clear headers and hierarchy
- Make action steps explicit and numbered
- Add expected outcomes
- Validate with
references/checklist.md
Summary
Create documentation that is:
- Scannable - Headers, bullets, whitespace
- Actionable - Clear steps, working examples
- Progressive - Quick start → concepts → advanced
- Accessible - Low cognitive load, clear language
- Consistent - Same patterns throughout
Always reference references/adhd-patterns.md for detailed guidance and references/checklist.md for validation. Use templates from assets/ as starting points for common documentation types.