Thematic Technical Documentation Generator

Generate comprehensive, publication-quality technical manuals with thematic storytelling using multi-agent orchestration.

What This Skill Does

Transforms dry technical topics into engaging, memorable documentation through:

• •Multi-agent parallel content generation - 8 chapters written simultaneously
• •Thematic metaphor system - Make complex topics memorable (e.g., git → Victorian railways)
• •AI-generated illustrations - Custom artwork matching your theme
• •Publication-ready output - Professional structure with front/back matter
• •Automated quality assurance - 98%+ quality scores with comprehensive validation

When to Use

• •Creating internal technical documentation with personality
• •Generating training materials that need to be memorable
• •Building comprehensive guides that stand out from typical docs
• •Transforming complex topics into accessible narratives
• •Team onboarding materials that people actually want to read

Example Usage

Basic Usage

# Generate a Victorian railway-themed git worktree manual
Use this skill with:
  topic: "git worktree safety and best practices"
  theme: "Victorian railway operations (1880s-1920s)"
  chapters: 8
  include_illustrations: true

Advanced Usage

# Art Deco automation theme for API documentation
Use this skill with:
  topic: "microservices architecture patterns"
  theme: "Art Deco automation and streamlined design"
  audience: "intermediate DevOps engineers"
  chapters: 10
  word_count: {min: 3000, max: 4000}
  illustration_count: 8
  character_guide: true
  output_dir: "./docs/architecture-manual"

Quick Reference Guide

# Minimal setup for quick guide (no illustrations)
Use this skill with:
  topic: "Docker security best practices"
  theme: "Maritime navigation safety protocols"
  chapters: 5
  comprehensive_vs_quick: "quick-reference"
  include_illustrations: false

What You Get

Primary Deliverable:

• •Complete manual (30,000+ words) in single markdown file
• •Professional front matter (foreword, TOC, usage guide)
• •Complete back matter (appendices, index, glossary, statistics)

Visual Assets (if illustrations enabled):

• •6-8 AI-generated illustrations matching theme
• •High-resolution PNGs (1024px+ minimum dimension)
• •Complete integration documentation
• •Alt text for accessibility

Quality Documentation:

• •Comprehensive QA report with metrics
• •Theme consistency validation
• •Technical accuracy verification
• •Publication readiness assessment

Supporting Files:

• •Individual chapter source files
• •Theme proposal document
• •Image integration guides
• •Sample integration examples

Parameters

Required

Optional

How It Works

Phase 1: Adversarial Theme Research (15-30 min)

Two agents collaboratively design theme and structure, challenging each other's proposals.

Agents:

• •Theme Designer: Proposes aesthetic, visual identity, tone, metaphor mappings
• •Structure Architect: Challenges theme viability, proposes chapter outline

Output: THEME_PROPOSAL.md (synthesized vision both agents approve)

Phase 2: Parallel Content Generation (30-60 min)

Each chapter generated independently by specialized agent, all running concurrently.

Agents: N chapter agents (one per chapter, typically 8)

Outputs: CHAPTER_1_*.md through CHAPTER_N_*.md

Key Design: Chapters are self-contained with no cross-dependencies, enabling true parallelism.

Phase 3: Publisher Assembly (15-30 min)

Publisher agent synthesizes chapters into cohesive manual with transitions.

Tasks:

• •Create front matter (title, copyright, foreword, TOC, usage guide)
• •Integrate all chapters with smooth transitions
• •Create back matter (appendices, index, glossary, statistics, colophon)
• •Handle missing chapters gracefully

Output: THE_COMPLETE_MANUAL.md (unified publication)

Phase 4: Visual Enhancement (15-30 min, optional)

Illustrator generates thematic imagery using AI.

Tasks:

• •Generate 6-8 illustrations matching theme
• •Ensure visual consistency (color palette, era, style)
• •Create comprehensive documentation
• •Provide alt text for accessibility

Outputs: Images + integration guides

Phase 5: Quality Assurance (15-30 min)

QA agent validates all deliverables against quality standards.

Validates:

• •Structural integrity (front/back matter complete)
• •Theme consistency (no anachronisms, metaphor accuracy)
• •Technical accuracy (code examples, commands)
• •Documentation quality (completeness, accessibility)
• •Publication readiness (no placeholders, proper licensing)

Output: QA_FINAL_REPORT.md with APPROVED/REJECTED recommendation

Success Stories

Victorian Railway Git Safety Manual

• •Topic: Git worktree safety and best practices
• •Theme: Victorian railway operations (1880s-1920s)
• •Results:
  • •30,606 words across 6 chapters
  • •6 Victorian illustrations (signal towers, brass instruments)
  • •98.4% quality score from QA
  • •Publication-ready on first execution
  • •Character: Cornelius Worktree (elderly railway dispatcher)

Excerpt:

"Dear Reader and Fellow Dispatcher, you hold in your hands a manual born of necessity. In the modern age of distributed version control, we find ourselves managing not merely a single line of development, but entire networks of parallel tracks..."

Tips for Best Results

Theme Selection

• •Choose themes with rich visual vocabulary: Victorian, Art Deco, Space Age, Medieval
• •Match theme to content domain when possible: Railways→branching, Architecture→structure
• •Consider character potential: Who naturally exists in this world?
• •Avoid overly abstract themes: Concrete metaphors work better

Scope Planning

• •8 chapters is optimal: Comprehensive coverage without overwhelming length
• •Allow variance in chapter length: Quality > rigid word counts
• •Plan for 75% completion: Missing 1-2 chapters is acceptable if acknowledged
• •Front/back matter adds ~20%: Factor this into total length

Visual Enhancement

• •Enable illustrations: Images significantly boost engagement
• •6 images is ideal: Cover, character, 4 concepts/diagrams
• •Budget time for iteration: AI image generation may require refinement
• •Document everything: Image prompts, models used, regeneration instructions

Quality Assurance

• •Trust the QA gate: 95%+ scores indicate publication readiness
• •Address critical issues only: Minor issues rarely block publication
• •Expect some variance: Parallel agents produce slightly different styles
• •Publisher smooths inconsistencies: Trust the synthesis process

Requirements

Essential

• •Claude Code CLI with skill support
• •Task orchestration capability
• •File system write access
• •Minimum context: ~100K tokens (for 8 chapters)

Optional

• •fal-text-to-image skill (for illustrations)
• •pandoc (for PDF export)
• •Markdown linter (for validation)

Limitations

• •Context window: Very large manuals (12+ chapters) may exceed limits
• •AI image generation: Requires API access and credits (fal.ai)
• •Execution time: 2-3 hours total (not instant)
• •Theme quality: Success depends on metaphor strength
• •Manual review: QA catches most issues but human review recommended

Troubleshooting

Problem: "Chapter agents incomplete"

• •Solution: Retry failed chapters or accept partial completion with transitional notes

Problem: "Illustration generation fails"

• •Solution: Check fal-text-to-image skill installation, API key, credits

Problem: "Context window exceeded"

• •Solution: Reduce chapter count or word count targets

Problem: "Theme feels forced"

• •Solution: Choose more natural metaphor, consult examples/

Problem: "QA rejects output"

• •Solution: Review critical issues, re-run appropriate phase (usually chapter agents)

License

This skill is released under the Unlicense (public domain). Generated manuals inherit this license unless you specify otherwise.

Support

• •Documentation: See docs/ directory in skill package
• •Examples: See examples/ directory
• •Issues: https://github.com/delorenj/thematic-doc-generator/issues

Generated manuals are publication-ready. No additional editing required (though always welcome).