| name | diataxis-documentation-architect |
| description | Workflow for auditing, designing, and writing structured documentation based on the Diátaxis Framework (Tutorials, How-to, Reference, Explanation). |
| license | MIT |
Diátaxis Documentation Architect Skill
Overview
This skill outlines the workflow to design documentation architecture and create high-quality documentation strictly adhering to the Diátaxis Framework. It ensures every piece of documentation serves one specific purpose and does not mix modes. This skill accompanies the @DiataxisDocumentationArchitect agent.
When to Use
- When creating user-facing or developer-facing documentation.
- When generating tutorials, how-to guides, reference material, or conceptual explanations.
🧭 The 4 Quadrants (Strict Rules)
1. 🎓 TUTORIALS (Learning-oriented)
- Goal: Allow the beginner to learn by doing a specific project.
- Characteristics: Instructional, step-by-step, builds understanding incrementally. Assumes no prior knowledge.
- Voice: Second person ("You"). Encouraging and prescriptive.
- Rule: NO abstract theory. NO choices/alternatives. Just "do this, then do that."
2. 🛠️ HOW-TO GUIDES (Task-oriented)
- Goal: Solve a specific problem or complete a task.
- Characteristics: A recipe. Series of steps to achieve a concrete result. Assumes some familiarity.
- Voice: Second person ("You"). Direct and action-oriented.
- Rule: NO teaching "basic concepts". Get straight to the solution.
3. 📖 REFERENCE (Information-oriented)
- Goal: Provide factual description of components.
- Characteristics: Concise, exhaustive. API specs, class descriptions, parameter lists.
- Voice: Third person or passive voice. Technical, dry, and austere.
- Rule: NO instructional steps. Just facts. Map the code 1:1 to text.
4. 💡 EXPLANATION (Understanding-oriented)
- Goal: Deepen understanding and clarify context, background, and "Why".
- Characteristics: Discursive, contextual. Discusses design decisions, trade-offs, and concepts.
- Voice: Engaging narrative.
- Rule: NO code snippets (unless for illustration). NO instructions.
⚙️ Operational Workflow
Follow this process sequentially:
Phase 1: Audit & Clarify
- Analyze Request: Determine the target audience, the project's maturity, and existing materials.
- Clarification Checkpoint: If the request is too broad, ask the user which specific component or quadrant to focus on first. MUST ask whether they prefer Markdown (
.md) or Plain Text (.txt).
- Scan Codebase: Use search/read tools to look at the actual code, functions, or APIs.
Phase 2: Design & Outline
- Propose Strategy: Tell the user: "I recommend writing a [Quadrant Name] document to achieve this."
- Outline: Create a bulleted outline of the document structure tailored to the specific quadrant.
- Wait for Approval: Do not write the full document until the user approves the outline.
Phase 3: Drafting & File Creation
- Write the content in clear, professional formatting (in Bahasa Indonesia by default).
- Verify Code: Ensure every code snippet in the docs matches the actual codebase logic perfectly.
- File Management: Save the document to a logically categorized folder (e.g.,
/docs/tutorials/, /docs/reference/).
🛑 Anti-Patterns (What to Avoid)
- The "All-in-One" Trap: Do not write a document that tries to teach a concept AND list every API parameter AND show a tutorial. Split them up into separate files.
- Assuming Knowledge: In Tutorials, assume zero knowledge. In How-Tos, assume basic competence.
- Outdated Info: Always verify facts against the current codebase results.
