explanation-techniques

name	explanation-techniques
description	Evidence-based explanation techniques for technical documentation. Use when creating documentation, explaining systems, or choosing the right approach for technical communication needs.

Select and combine the explanation techniques based on your documentation needs, audience, and goals:

• Read instructions/technical-explanation-structure.md if you need to create technical documentation describing systems, implementations, or code behavior. Key situations: system architecture documentation, API explanations, code walkthroughs, technical onboarding. Apply when the goal is deep understanding of "how" and "why" rather than business decisions.
• Read instructions/information-mapping-methodology.md if you need to create reference documentation, API guides, or procedural content. Key indicators: need for 3x faster learning, 40% better task completion, reducing support requests by 25-50%. Essential for complex technical procedures, system documentation, or training materials. Most effective when content must be quickly scannable and retrievable.
• Read instructions/minimalist-documentation-approach.md if you need to create quick-start guides, mobile documentation, or time-constrained user content. Key metrics: 33% reduction in learning time, documentation size, and improved task completion. Use when users need immediate action, not comprehensive understanding. Ideal for developer tools, CLI utilities, or API quickstarts. Apply when documentation frequently becomes outdated.
• Read instructions/progressive-disclosure-pattern.md if you're documenting complex systems, multi-level audiences, or need to reduce overwhelm. Shows 25% improvement in task completion, 40% reduction in errors. Use for configuration wizards, API documentation with basic/advanced modes, or tutorials. Key phrases: "getting started", "advanced topics", "deep dive". Apply when expertise levels vary significantly.
• Read instructions/c4-model-visualization.md if you need to create software architecture documentation or explain system design to mixed audiences (technical and non-technical). Key scenarios: architecture reviews, onboarding, system documentation. 10,000+ practitioners globally validate effectiveness. Essential for microservices, distributed systems, or when "how does it all fit together" questions arise.
• Read instructions/cognitive-load-management.md when creating any technical documentation (apply by default). Critical for complex algorithms, multi-step procedures, or conceptual explanations. Key indicators: complex nested logic, multiple abstraction levels, or dense technical content. Research shows 7±2 item limit for working memory. Use when explaining TypeScript generics, async patterns, or architectural decisions.
• Read instructions/architecture-decision-records.md if you need to document any significant technical decision. Critical for "why did we choose X over Y" questions, onboarding context, or audit trails. ThoughtWorks "Adopt" recommendation since 2018. Essential when multiple valid options exist, trade-offs are complex, or decisions affect multiple teams. Store in version control with code.
• Read instructions/tsdoc-type-driven-explanation.md if you're documenting TypeScript codebases (use by default). Essential for libraries, shared components, or public APIs. Use when types are complex, generics are involved, or discriminated unions exist. Critical for maintaining synchronized docs and code. Microsoft standard ensures tool compatibility across TypeDoc, API Extractor, and ESLint.
• Read instructions/migration-pattern-explanation.md if you need to document breaking changes, system migrations, or architectural transitions. Use when moving from monolith to microservices, upgrading major versions, or switching technologies. Netflix, Atlassian, and AWS validate these patterns. Critical when risk is high, rollback needed, or gradual migration required.
• Read instructions/socratic-questioning-method.md if you need to create conceptual understanding, debugging guides, or self-service documentation. Shows 3x improvement in knowledge retention, 45% reduction in support tickets. Apply when readers need deep understanding, not just task completion. Effective for architecture documentation, design patterns, or troubleshooting guides.
• Read instructions/before-after-bridge-technique.md if you need to create migration guides, refactoring documentation, or upgrade paths. Use when showing code evolution, API changes, or architectural transformations. Most effective when change is complex but benefits are clear. Essential for building stakeholder buy-in or demonstrating improvements.
• Read instructions/technical-analysis-framework.md if you need to analyze technical decisions, architectural implications, and system integration concerns. Apply when explaining "why" technical approaches make sense within existing system architecture. Essential for providing insights beyond plan summaries.
• Read instructions/documentation-quality-principles.md if you need to validate generated documentation (apply to all documentation). Essential for maintaining documentation standards, ensuring completeness, and validating accuracy. Use to verify explanations meet evidence-based criteria. Critical for documentation that will be published or shared externally.