Adr 018 Five Expansion Types

EPGOAT Documentation - Architectural Decisions

ADR-018: Five Expansion Types for Educational Content

Date: 2025-11-10 Status: ✅ Accepted Deciders: CTO (Claude Code AI) Tags: #documentation #content #ux

Context

YAML expansion files need defined types for different kinds of educational content. What types should we support?

Decision

Support exactly 5 expansion types, each with specific semantics and formatting:

  1. 💡 example: Code examples with explanations
  2. 📊 diagram: Mermaid.js diagrams with captions
  3. 📖 verbose: Multi-paragraph detailed explanations
  4. ⚠️ pitfall: Common mistakes with solutions
  5. 🎯 why: Business/technical rationale sections

Rationale

Why These 5?

  • example: Most common educational need (show, don't tell)
  • diagram: Visual learners need architecture/workflow diagrams
  • verbose: Some concepts need deep explanation
  • pitfall: Prevent common mistakes proactively
  • why: Developers want to understand rationale, not just rules

Why NOT More Types?

  • 5 types cover all educational needs
  • More types = confusion about which to use
  • Semantic clarity: each type has clear purpose
  • Build system complexity grows with more types

Why Emoji Prefixes?

  • Visual distinction in rendered HTML
  • Quick scanning (see 💡 = example)
  • Adds personality to docs

Consequences

Positive

  • ✅ Clear semantics (know which type to use)
  • ✅ Comprehensive coverage (all educational needs met)
  • ✅ Visual distinction (emoji prefixes)
  • ✅ Extensible (can add more types if needed)

Negative

  • ❌ Limited to 5 types (but sufficient)
  • ❌ Must choose correct type (but clear guidelines)

Implementation

Current State: - ✅ All 5 types implemented in build system - ✅ 150+ expansions created across 4 files - ✅ Emoji prefixes rendering correctly

Type Distribution (_SYSTEM.expansions.yml example): - example: 2 (EPG pipeline, database queries) - diagram: 2 (architecture, pipeline flow) - verbose: 2 (C4 model, token compression) - pitfall: 2 (M3U parsing, timezone handling) - why: 2 (soft deletes, token compression)

References