explanation-docs

Create structured documents explaining the rationale behind software and product design decisions.

Updated Mar 30, 2026

Search Tags:#architecture #documentation #reasoning #explanation #concepts #design-rationale

Ready to run

npx skills add https://github.com/erlebach/gordon --skill explanation-docs-erlebach

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: explanation-docs
Source: https://github.com/erlebach/gordon/tree/main/skills/explanation-docs
Command: npx skills add https://github.com/erlebach/gordon --skill explanation-docs-erlebach

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires docs-style.

What problem does it solve?

Explanations provide readers with a structured way to learn why systems work as they do, not just how to use them.

Core Features & Use Cases

Clear, structured explanations with rationale and context
Architecture-level overviews and decision justification for design patterns
Use Case: a coder or architect seeks to understand the reasoning behind a component.

Quick Start

Provide a concept explanation to help readers build a clear mental model of how and why it works.

Frequently Asked Questions about explanation-docs

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I write documentation that explains architecture rationale and design trade-offs?▼

Documentation explaining architecture rationale should provide structured explanations covering core concepts, rationale, trade-offs, alternatives, and implications. Use an organized document template to help readers understand why systems work the way they do, not just how to use them.

What is the best way to explain software design concepts to architects seeking deep understanding?▼

Explaining design concepts requires structured overviews that justify architectural decisions and design patterns. Aim explanations at readers seeking architectural context and rationale behind choices across software or product domains to build a clear mental model.

How do I structure a technical explanation to cover system reasoning and implications?▼

Structure technical explanations using a document template that covers core concepts, rationale, trade-offs, alternatives, and implications. This organized approach ensures readers seeking deep understanding can follow the reasoning behind system choices effectively.

When do I need explanation documentation instead of standard how-to guides?▼

You need explanation documentation when readers seek to understand why systems work as they do rather than just how to use them. It is essential for providing architectural context and justifying design decisions for coders and architects.

Does this approach to concept documentation work for both software and product domains?▼

Yes, this concept documentation approach works for both software and product domains. It provides structured explanations with rationale and context, helping readers understand design choices and architectural decisions across diverse domains.

What are the limitations of using structured templates for design rationale explanations?▼

Structured templates for design rationale explanations ensure comprehensive coverage of trade-offs and alternatives but may require significant depth. They are aimed at readers seeking deep understanding, so they might be excessive for simple feature documentation.