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:

1. Load appropriate skeleton from @templates/document-skeletons.md
2. 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
3. Plan navigation aids (TOC for >500 words, cross-references)
4. 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:

1. Apply voice appropriate to persona (from @references/style-guide.md)
2. Use sentence length appropriate to reading_level
3. Handle technical terminology per audience expertise
4. Format code blocks for copy-paste readiness
5. Use callouts sparingly and purposefully

Content Quality During Writing:

• One concept per sentence/step
• Active voice preferred
• Second person for instructions ("you")
• Terms defined on first use
• Examples are realistic and minimal

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:

• Reasoning chain is traceable (each claim has foundation)
• Assumptions are inventoried and documented
• Confidence levels are calibrated appropriately
• No logical leaps without explanation
• Document type correctly identified and consistent
• Structure matches skeleton for this type
• Title accurately reflects content and type
• Section flow is logical

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:

• Scan pattern works (code blocks → headings → bold → prose)
• Code is copy-paste ready
• Prerequisites are upfront
• Can skip to what they need

For Anxious Novice persona:

• Every step is explicit
• Verification points are clear
• Recovery paths exist for mistakes
• No assumed knowledge beyond prerequisites

For Scanning Executive persona:

• Key questions are answerable (What? So what? Now what?)
• Tradeoffs are visible
• Recommendations are clear
• Impact is quantified where possible

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:

• Primary persona needs met
• Voice consistent with persona expectations
• Cognitive load appropriate for audience
• Entry/exit points clear

Mode Boundary Reasoning Audit:

Detect implicit transitions between documentation modes that confuse readers.

1. Map each section's mode (learning | doing | looking up)
2. Identify all transitions between modes
3. Verify markers for each transition (explicit signals)
4. REASON through each transition: Why is this mode shift necessary? Is the reader prepared?
5. 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:

• All technical terms defined or linked
• No broken references to undefined concepts
• No forward references without eventual fulfillment

Promise Verification:

• Title delivers what it promises
• All "What You'll Learn" items taught
• All stated outcomes achievable

Final Readability Pass:

• Read-aloud test (mark stumbles)
• Heading scan test (structure clear from headings)
• "Can I find X?" test (information findable)
• Paragraph length audit (max 5 sentences)

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:

• Document type correctly classified (single Diátaxis quadrant)
• Reader profile complete with confidence >= 0.85
• Cognitive load strategy documented and applied
• Layer A (Meta-Cognitive Self-Audit) passed
• Layer B (Reader Persona Simulation) passed
• Layer C (Experience + Mode Boundary) validation passed
• Mode boundary reasoning audit passed with explicit reasoning
• MECE verification completed
• Style guide compliance verified
• All examples tested/verified

---

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