| name | create-documentation |
| description | Generate reader-centered documentation aligned with the Diátaxis framework and optimized for cognitive load management. Creates tutorials, how-to guides, explanations, and reference documentation with multi-layer quality validation.
PROACTIVELY activate for: (1) Write tutorials for learning new skills, (2) Create how-to guides for specific tasks, (3) Write explanations for understanding concepts, (4) Generate reference documentation for APIs or features, (5) Document systems, features, or processes, (6) Create user guides or onboarding documentation.
Triggers: "write documentation for", "create docs", "document this", "write a tutorial for", "how-to guide for", "explain [concept]", "reference documentation for", "API docs for", "user guide for", "document the", "create documentation"
|
Create Documentation
Generate high-quality, reader-centered documentation using Diátaxis framework alignment and cognitive load optimization.
Purpose
This skill produces documentation that serves readers effectively by:
- Diátaxis alignment — Matching content structure to reader intent (learning, doing, understanding, or lookup)
- Cognitive load management — Minimizing extraneous load, managing intrinsic complexity, maximizing schema-building
- Reader persona adaptation — Tailoring voice, depth, and structure to Anxious Novice, Developer, or Scanning Executive
- Multi-layer validation — Verifying structure, content, and reader experience before publication
When to Use
Ideal for:
- User-facing documentation (tutorials, guides, onboarding)
- API and technical reference documentation
- Concept explanations for technical or non-technical audiences
- Feature documentation requiring multiple reader perspectives
- Documentation that must serve readers at different expertise levels
Avoid when:
- Internal notes or scratch documentation (no structure needed)
- Highly specialized domain requiring SME validation first
- Legal or compliance documentation (requires legal review)
- Marketing copy (different skill set)
- Documentation requiring real-time data or dynamic content
Workflow
Step 1: Document Type Classification
Determine which Diátaxis quadrant fits the reader's needs:
Reader's Primary Need → Document Type
─────────────────────────────────────
"Teach me to do X" → Tutorial
"Help me accomplish Y" → How-To
"Help me understand Z" → Explanation
"What are the options for W" → Reference
Decision Tree:
| Question | Yes Answer | No Answer |
|---|
| Is the reader trying to LEARN something? | Continue below | How-To or Reference |
| Is it learning by DOING (practical)? | Tutorial | Explanation |
| Does the reader have a SPECIFIC task? | How-To | N/A |
| Is the reader LOOKING UP information? | Reference | N/A |
Output: doc_type (tutorial | how_to | explanation | reference)
Load: @references/tutorial-framework.md, @references/howto-framework.md, @references/explanation-framework.md, or @references/reference-framework.md based on type.
Step 2: Reader Analysis & Confidence Loop
Build a complete reader profile through iterative refinement. Do not proceed until confidence reaches threshold.
Confidence Loop Logic:
confidence = 0.0
iterations = 0
WHILE confidence < 0.85 AND iterations < 3:
1. ASSESS what we know about the reader:
- expertise_level: novice | intermediate | expert
- persona: Anxious Novice | Developer | Scanning Executive
- prior_knowledge: What they already know
- reading_context: Where/how they'll read this
- success_definition: What "done" looks like for them
2. IDENTIFY gaps in reader understanding:
- Unknown expertise level?
- Unclear persona fit?
- Missing context about prior knowledge?
- Undefined success criteria?
3. RESOLVE gaps:
IF user available:
Ask specific clarifying questions
ELSE:
Make explicit assumptions with confidence scores
Document assumptions in output
4. RECALCULATE confidence based on profile completeness
iterations++
Reader Dimensions:
| Dimension | Question | Impact |
|---|
expertise_level | How much do they already know? | Vocabulary, depth, assumed knowledge |
persona | What's their emotional/practical state? | Voice, structure, pacing |
prior_knowledge | What specific knowledge do they have? | What to explain vs. assume |
reading_context | How/where will they read? | Length, structure, format |
success_definition | What does success look like for them? | Scope, endpoints |
Output: Complete reader profile with confidence >= 0.85
Load: @references/reader-personas.md
Step 3: Cognitive Load Planning
Design for optimal information absorption given the topic and reader.
Three-Load Assessment:
| Load Type | Assessment | Optimization |
|---|
| Intrinsic | How complex is this topic inherently? | Sequence, chunk, scaffold |
| Extraneous | What presentation overhead can we eliminate? | Remove noise, co-locate info |
| Germane | How can we help build lasting understanding? | Examples, connections, reflection |
Load Strategy by Document Type:
| Type | Intrinsic | Extraneous | Germane |
|---|
| Tutorial | Manage carefully | Minimize aggressively | Maximize |
| How-To | Assume away | Eliminate | Optional (via links) |
| Explanation | Embrace complexity | Minimize | Maximize |
| Reference | Minimal per entry | Near zero | N/A |
Output: Cognitive load strategy document
Load: @references/cognitive-load.md
Step 4: Structure Selection
Select and customize document skeleton based on type and reader profile.
Process:
- Load appropriate skeleton from
@templates/document-skeletons.md
- Adapt sections based on reader persona:
- Anxious Novice: Add verification, recovery paths, reassurance
- Developer: Strip to essentials, ensure copy-paste ready
- Scanning Executive: Add "why" sections, connections, depth options
- Plan navigation aids (TOC for >500 words, cross-references)
- Determine appropriate length based on reading_level:
- Grade 8: Max 1500 words
- Grade 12: Max 3000 words
- Professional: As needed, chunked appropriately
Output: Customized document structure/outline
Load: @templates/document-skeletons.md
Step 5: Content Generation
Write documentation following the selected structure, type-specific patterns, and style guidelines.
Type-Specific Patterns:
| Type | Pattern | Key Characteristics |
|---|
| Tutorial | Step-by-step learning | Verification after each step, worked examples, recovery paths |
| How-To | Task completion | Imperative verbs, copy-paste ready, minimal context |
| Explanation | Understanding | Multiple perspectives, "why" focus, connections |
| Reference | Information lookup | Consistent entries, complete coverage, self-contained |
Style Application:
- Apply voice appropriate to persona (from
@references/style-guide.md)
- Use sentence length appropriate to reading_level
- Handle technical terminology per audience expertise
- Format code blocks for copy-paste readiness
- Use callouts sparingly and purposefully
Content Quality During Writing:
Output: Draft documentation
Load: @references/style-guide.md, appropriate framework reference
Step 6: Multi-Layer Validation
Validate documentation across three layers to ensure quality.
Layer A: Meta-Cognitive Self-Audit
Audit your own reasoning and assumptions before validating the document.
Checklist:
Load: @references/self-audit-protocol.md#reasoning-chain-audit, @references/self-audit-protocol.md#assumption-inventory, @references/checklists.md#layer-a-structural-validation
Layer B: Reader Persona Simulation
Simulate reading the document as each relevant persona.
For Developer persona:
For Anxious Novice persona:
For Scanning Executive persona:
Load: @references/reader-personas.md, @references/checklists.md#layer-b-content-validation
Layer C: Experience Validation + Mode Boundary Audit
Verify document serves readers well from their perspective.
Persona Alignment Check:
Mode Boundary Reasoning Audit:
Detect implicit transitions between documentation modes that confuse readers.
- Map each section's mode (learning | doing | looking up)
- Identify all transitions between modes
- Verify markers for each transition (explicit signals)
- REASON through each transition: Why is this mode shift necessary? Is the reader prepared?
- Check for red flags:
- Sudden jargon increase
- Unexplained prerequisites mid-document
- "Obviously" or "Simply" language
- Explanation content in how-to
- Instructions in explanation
Load: @references/checklists.md#layer-c-experience-validation, @references/checklists.md#mode-boundary-reasoning-audit
Step 7: Final Polish & Self-Audit
Ensure completeness, coherence, and publication-readiness.
MECE Verification:
| Check | Question | If Fails |
|---|
| Mutually Exclusive | Do any sections overlap? | Merge or delineate |
| Collectively Exhaustive | Are there gaps in coverage? | Add missing content |
Orphan Concept Detection:
Promise Verification:
Final Readability Pass:
Output: Publication-ready documentation
Load: @references/self-audit-protocol.md
Output Format
# [Document Title]
## Metadata
- **Type:** [Tutorial | How-To | Explanation | Reference]
- **Audience:** [expertise_level], [persona]
- **Reading Level:** [grade_8 | grade_12 | professional]
- **Estimated Read Time:** [X minutes]
---
[Document content following selected skeleton and type-specific structure]
---
## Quality Attestation
- **Diátaxis alignment:** Confirmed [type]
- **Cognitive load optimized:** Yes
- **Validation layers passed:** A, B, C
- **Reader profile confidence:** [X.X]
- **Assumptions made:** [List if any]
Quality Gates
Before completing documentation:
Parameters
| Parameter | Default | Options | Description |
|---|
doc_type | auto_detect | tutorial, how_to, explanation, reference | Diátaxis document type |
topic | — | (required) | What to document |
audience.expertise_level | intermediate | novice, intermediate, expert | Reader's technical expertise |
audience.persona | auto_detect | anxious_novice, developer, scanning_executive | Reader persona |
reading_level | grade_12 | grade_8, grade_12, professional | Complexity/vocabulary level |
confidence_threshold | 0.85 | 0.0-1.0 | Minimum confidence before proceeding from Step 2 |
include_examples | true | true, false | Include worked examples |
validation_depth | standard | quick, standard, comprehensive | How thorough to validate |
References
This skill uses the following reference files:
| Reference | Purpose |
|---|
@references/reader-personas.md | Three reader persona definitions and selection guide |
@references/cognitive-load.md | Cognitive load theory and documentation strategies |
@references/style-guide.md | Writing style, voice, and formatting standards |
@references/tutorial-framework.md | Tutorial-specific guidance and patterns |
@references/howto-framework.md | How-to guide specific guidance |
@references/explanation-framework.md | Explanation documentation guidance |
@references/reference-framework.md | Reference documentation guidance |
@references/checklists.md | All validation checklists (Layers A, B, C + Mode Audit) |
@references/self-audit-protocol.md | MECE verification and final audit protocol |
@templates/document-skeletons.md | Ready-to-use templates for all four types |
Examples
Example 1: Tutorial Request
request: "Create a tutorial for setting up Firebase authentication"
analysis:
doc_type: tutorial (learning by doing)
expertise_level: novice
persona: anxious_novice (worried about breaking things)
reading_level: grade_12
workflow:
step_1: Classified as Tutorial (learning-oriented, practical)
step_2: Reader profile - novice, anxious, needs reassurance
step_3: High germane load, low extraneous, managed intrinsic
step_4: Tutorial skeleton + extra verification steps
step_5: Write with reassuring voice, explicit steps
step_6: All three layers validated
step_7: MECE verified, no orphans
output: Step-by-step tutorial with verification at each step,
recovery paths for common errors, "What You've Learned" summary
Example 2: How-To Request
request: "How-to guide for resetting a user's password"
analysis:
doc_type: how_to (task completion)
expertise_level: intermediate
persona: developer (needs it done fast)
reading_level: professional
workflow:
step_1: Classified as How-To (task-oriented)
step_2: Reader profile - competent, time-pressured
step_3: Minimal all loads, optimize for speed
step_4: How-To skeleton, stripped to essentials
step_5: Imperative verbs, copy-paste commands
step_6: Layers A and B focus (C lighter for practitioners)
step_7: MECE verified
output: Numbered steps with prerequisites, copy-paste commands,
result verification, troubleshooting section
Example 3: Explanation Request
request: "Explain how database indexing works"
analysis:
doc_type: explanation (understanding)
expertise_level: intermediate
persona: scanning_executive (wants to understand deeply)
reading_level: grade_12
workflow:
step_1: Classified as Explanation (understanding-oriented)
step_2: Reader profile - curious, wants depth
step_3: Higher intrinsic OK, maximize germane (connections)
step_4: Explanation skeleton with multiple perspectives
step_5: Include why, analogies, related concepts
step_6: Full validation with mode audit
step_7: MECE verified, connections documented
output: Concept explanation with multiple mental models,
practical grounding, related concepts section
Example 4: Reference Request
request: "Generate API reference for the configuration options"
analysis:
doc_type: reference (information lookup)
expertise_level: expert
persona: developer (looking up specific info)
reading_level: professional
workflow:
step_1: Classified as Reference (information-oriented)
step_2: Reader profile - expert, needs quick lookup
step_3: Near-zero extraneous, minimal intrinsic per entry
step_4: Reference skeleton with consistent entry format
step_5: Complete entries, no narrative, all options documented
step_6: Focus on consistency and completeness
step_7: MECE verified, index complete
output: Alphabetically organized reference with consistent
entry format, parameter tables, minimal examples, full index
