feat: enhance Explanation template with question-driven investigation methodology

docs/0002-separate-common-and-repository-specific-documentation.md

@@ -0,0 +1,56 @@
+# 2. Separate Common and Repository-Specific Documentation
+
+Date: 2025-03-05
+
+## Status
+
+Accepted
+
+## Context
+
+The project consists of a meta repository containing multiple sub-repositories, each with its own documentation needs. Currently, documentation is scattered across repositories, leading to:
+
+1. Duplication of common documentation (e.g., authentication procedures)
+2. Inconsistent locations for similar information
+3. Difficulty in maintaining shared procedures
+4. Potential confusion for developers about where to find or place documentation
+
+## Decision
+
+We will organize documentation following these principles:
+
+1. Common Documentation (Meta Repository)
+   - Place shared how-to guides, tutorials, and ADRs in the meta repository's `.diataxis` directory
+   - Common documentation includes:
+     - Authentication procedures
+     - Environment setup
+     - Shared development practices
+     - Cross-repository architectural decisions
+
+2. Repository-Specific Documentation (Sub-repositories)
+   - Keep repository-specific documentation in each repository's `.diataxis` directory
+   - Include:
+     - Repository-specific ADRs
+     - Component-specific how-to guides
+     - Local implementation details
+     - Repository-specific tutorials
+
+3. Cross-References
+   - Repository-specific documentation should reference common documentation using relative paths
+   - Each repository's README should point to both common and specific documentation locations
+
+## Consequences
+
+### Positive
+
+- Eliminates documentation duplication
+- Provides clear guidance on documentation placement
+- Simplifies maintenance of shared procedures
+- Improves discoverability of common practices
+- Maintains consistency with Diátaxis framework principles
+
+### Negative
+
+- Requires initial effort to reorganize existing documentation
+- Developers need to consider documentation placement carefully
+- May need to handle documentation versioning if common procedures vary by repository version

lib/diataxis/diataxis.rb

@@ -321,41 +321,58 @@ def content
       <<~CONTENT
         # #{title}
 
-        This document explores [TOPIC] following a question-driven investigation that reveals the underlying concepts step by step.
+        This document explores [DESCRIBE THE MAIN TOPIC/CONCEPT] following a question-driven investigation that reveals the underlying concepts step by step.
 
         ## Question 1: [What is the fundamental question that started this investigation?]
 
-        [Brief context about why this question arose or what prompted the investigation.]
+        [Brief context about why this question arose or what prompted the investigation. What real-world need or problem led to this question?]
+
+        **How was this investigated?**
+
+        [Describe your research methodology: What did you search for? Where did you look? What tools or techniques did you use? What initial findings led you to dig deeper? Include specific file paths, search terms, or code sections that were key to discovery.]
+
+        [If applicable, describe the breakthrough moment or key insight that led to understanding:]
+
+        [List specific evidence with bullet points if helpful:]
+        - [Specific file/location that revealed key information]
+        - [Code section or configuration that confirmed the behavior]
+        - [Schema or documentation that validated the approach]
 
         **Answer**: [Clear, direct answer to the question]
 
-        [Detailed explanation with evidence, examples, or supporting details]
+        **Details:**
 
-        ## Question 2: [What was the next logical question that emerged?]
+        [Detailed explanation with evidence, examples, or supporting details. Include practical information about how to use what was discovered.]
 
-        [Context about why this question became important after learning from Question 1.]
+        **Testing Example:**
 
-        **Answer**: [Clear, direct answer]
+        [If applicable, provide a concrete example that readers can try themselves - code snippets, configuration files, commands, etc.]
 
-        [Supporting explanation with details, code examples, diagrams, etc.]
+        ```[language]
+        [example code or configuration]
+        ```
+
+        [Instructions for testing or using the example]
 
-        ## Question 3: [What deeper question arose as understanding developed?]
+        ## Question 2: [What was the next logical question that emerged?]
+
+        **How was this investigated?**
 
-        [Context about the progression of understanding.]
+        [Describe how this question naturally followed from Question 1. What additional research was needed? What connections were made between the first answer and this new question?]
 
         **Answer**: [Clear, direct answer]
 
-        [Detailed explanation]
+        [Supporting explanation with details, code examples, diagrams, etc.]
 
         ## [Continue with additional questions as needed...]
 
-        Each question should build naturally on the previous ones, showing the progressive discovery of understanding.
+        [Each question should build naturally on the previous ones, showing the progressive discovery of understanding. Include the investigation methodology for each question.]
 
         ## Key Insights Discovered
 
-        1. **[First major insight]**: [Brief explanation]
-        2. **[Second major insight]**: [Brief explanation]
-        3. **[Third major insight]**: [Brief explanation]
+        1. **[First major insight]**: [Brief explanation of what was learned]
+        2. **[Second major insight]**: [Brief explanation of what was learned]
+        3. **[Third major insight]**: [Brief explanation of what was learned]
         4. **[Additional insights as needed]**
 
         ## Related Topics