<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/architecture/divio-documentation/">
  <id>https://docs.spec-kitty.ai/architecture/divio-documentation/</id>
  <title>Why the Divio Documentation System?</title>
  <updated>2026-09-30T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/architecture/divio-documentation/"/>
  <summary>Why Spec Kitty organizes docs with the Divio four-type system, tutorials, how-to, reference, and explanation, so each user need maps to one doc type, not mixed-concern pages.</summary>
  <content type="html">&lt;span id=&quot;why-the-divio-documentation-system&quot;&gt;&lt;/span&gt;
&lt;p&gt;Spec Kitty uses the Divio documentation system to organize its docs. This document explains why we chose this system and how it works.&lt;/p&gt;
&lt;h2 id=&quot;the-problem-with-traditional-documentation&quot;&gt;The Problem with Traditional Documentation&lt;/h2&gt;
&lt;p&gt;Most documentation suffers from mixed concerns:&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Common problems&lt;/strong&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;A “quickstart” that’s actually a reference manual&lt;/li&gt;
&lt;li&gt;API reference mixed with tutorials&lt;/li&gt;
&lt;li&gt;No clear path for different user needs&lt;/li&gt;
&lt;li&gt;“Everything on one page” syndrome&lt;/li&gt;
&lt;li&gt;Documentation that tries to be everything to everyone&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;The result&lt;/strong&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Beginners can’t find where to start&lt;/li&gt;
&lt;li&gt;Experts can’t find the specific information they need&lt;/li&gt;
&lt;li&gt;Writers don’t know what to write&lt;/li&gt;
&lt;li&gt;Documentation becomes a dumping ground&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;the-four-types-of-documentation&quot;&gt;The Four Types of Documentation&lt;/h2&gt;
&lt;p&gt;The Divio system identifies four distinct types of documentation, each serving a different purpose:&lt;/p&gt;
&lt;h3 id=&quot;1-tutorials-learning-oriented&quot;&gt;1. Tutorials (Learning-Oriented)&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Purpose&lt;/strong&gt;: Teach a beginner through doing.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Characteristics&lt;/strong&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Hands-on, step-by-step instructions&lt;/li&gt;
&lt;li&gt;Complete working examples&lt;/li&gt;
&lt;li&gt;Focuses on learning, not accomplishing&lt;/li&gt;
&lt;li&gt;“Follow along with me”&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Spec Kitty example&lt;/strong&gt;: “Your First Feature with Spec Kitty” - walks through creating a feature from start to finish&lt;/p&gt;
&lt;h3 id=&quot;2-how-to-guides-task-oriented&quot;&gt;2. How-To Guides (Task-Oriented)&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Purpose&lt;/strong&gt;: Help accomplish a specific goal.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Characteristics&lt;/strong&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Assumes basic knowledge&lt;/li&gt;
&lt;li&gt;Goal-oriented (“How to X”)&lt;/li&gt;
&lt;li&gt;Practical steps&lt;/li&gt;
&lt;li&gt;Doesn’t explain underlying concepts&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Spec Kitty example&lt;/strong&gt;: “How to Review a work package” - steps to review, without explaining why review matters&lt;/p&gt;
&lt;h3 id=&quot;3-reference-information-oriented&quot;&gt;3. Reference (Information-Oriented)&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Purpose&lt;/strong&gt;: Describe the machinery.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Characteristics&lt;/strong&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Technical descriptions&lt;/li&gt;
&lt;li&gt;Accurate and complete&lt;/li&gt;
&lt;li&gt;Structured consistently&lt;/li&gt;
&lt;li&gt;“What it is, not what to do with it”&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Spec Kitty example&lt;/strong&gt;: “CLI Reference” - all commands, flags, and options documented&lt;/p&gt;
&lt;h3 id=&quot;4-explanations-understanding-oriented&quot;&gt;4. Explanations (Understanding-Oriented)&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Purpose&lt;/strong&gt;: Help understand concepts.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Characteristics&lt;/strong&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Background and context&lt;/li&gt;
&lt;li&gt;Why things work this way&lt;/li&gt;
&lt;li&gt;Alternative approaches considered&lt;/li&gt;
&lt;li&gt;“Understanding, not doing”&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Spec Kitty example&lt;/strong&gt;: This document you’re reading right now&lt;/p&gt;
&lt;h2 id=&quot;the-four-quadrants&quot;&gt;The Four Quadrants&lt;/h2&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;plaintext&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;                        &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;PRACTICAL                    THEORETICAL&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;                           &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;↓                              ↓&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;           &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;┌───────────────────────────┬───────────────────────────┐&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;           &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│                           │                           │&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt; &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;STUDYING  │        TUTORIALS          │       EXPLANATIONS        │&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;           &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│    (learning-oriented)    │  (understanding-oriented) │&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;           &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│                           │                           │&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;           &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│    &quot;Follow along to       │    &quot;Why does this work    │&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;           &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│     learn X&quot;              │     this way?&quot;            │&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;           &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│                           │                           │&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;           &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;├───────────────────────────┼───────────────────────────┤&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;           &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│                           │                           │&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt; &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;WORKING   │       HOW-TO GUIDES       │        REFERENCE          │&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;           &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│     (task-oriented)       │  (information-oriented)   │&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;           &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│                           │                           │&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;           &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│    &quot;Steps to             │    &quot;Complete list of      │&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;           &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│     accomplish X&quot;         │     all options&quot;          │&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;           &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│                           │                           │&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;           &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;└───────────────────────────┴───────────────────────────┘&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;h2 id=&quot;why-this-works&quot;&gt;Why This Works&lt;/h2&gt;
&lt;p&gt;Different users need different things at different times:&lt;/p&gt;






























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;User State&lt;/th&gt;&lt;th&gt;Need&lt;/th&gt;&lt;th&gt;Doc Type&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;New to Spec Kitty&lt;/td&gt;&lt;td&gt;Learn the basics&lt;/td&gt;&lt;td&gt;Tutorial&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Need to do something specific&lt;/td&gt;&lt;td&gt;Practical steps&lt;/td&gt;&lt;td&gt;How-To&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Looking up a specific flag&lt;/td&gt;&lt;td&gt;Accurate information&lt;/td&gt;&lt;td&gt;Reference&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Want to understand design decisions&lt;/td&gt;&lt;td&gt;Context and reasoning&lt;/td&gt;&lt;td&gt;Explanation&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;&lt;strong&gt;The same user&lt;/strong&gt; might need all four types at different times:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Day 1&lt;/strong&gt;: Follow the tutorial&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Week 1&lt;/strong&gt;: How to handle a specific case&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Week 2&lt;/strong&gt;: Look up command syntax&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Month 1&lt;/strong&gt;: Understand why the architecture is this way&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;how-spec-kitty-uses-divio&quot;&gt;How Spec Kitty Uses Divio&lt;/h2&gt;
&lt;h3 id=&quot;documentation-structure&quot;&gt;Documentation Structure&lt;/h3&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;plaintext&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;docs/&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;├── tutorial/                    # Learning-oriented&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│   ├── first-feature.md         # Your first feature end-to-end&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│   ├── working-with-agents.md   # Multi-agent basics&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│   └── ...&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;├── how-to/                      # Task-oriented&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│   ├── review-work-package.md   # How to review&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│   ├── resolve-conflicts.md     # How to handle merge conflicts&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│   └── ...&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;├── reference/                   # Information-oriented&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│   ├── cli-reference.md         # All commands and flags&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│   ├── configuration.md         # All config options&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│   └── ...&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;└── explanation/                 # Understanding-oriented&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;├── spec-driven-development.md&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;├── divio-documentation.md   # (this file)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;├── execution-lanes.md&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;└── ...&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;h3 id=&quot;cross-referencing&quot;&gt;Cross-Referencing&lt;/h3&gt;
&lt;p&gt;Each doc type links to related docs of other types:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Tutorial&lt;/strong&gt; links to &lt;strong&gt;Reference&lt;/strong&gt; for full command syntax&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;How-To&lt;/strong&gt; links to &lt;strong&gt;Explanation&lt;/strong&gt; for deeper understanding&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Reference&lt;/strong&gt; links to &lt;strong&gt;How-To&lt;/strong&gt; for usage examples&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Explanation&lt;/strong&gt; links to &lt;strong&gt;Tutorial&lt;/strong&gt; for hands-on learning&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;writing-guidelines&quot;&gt;Writing Guidelines&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;When writing tutorials&lt;/strong&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Use real examples the user can follow&lt;/li&gt;
&lt;li&gt;Don’t explain theory (link to explanations instead)&lt;/li&gt;
&lt;li&gt;Every step should work exactly as shown&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;When writing how-tos&lt;/strong&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Start with the goal (“How to…”)&lt;/li&gt;
&lt;li&gt;Give practical steps&lt;/li&gt;
&lt;li&gt;Don’t teach (link to tutorials instead)&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;When writing reference&lt;/strong&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Be complete and accurate&lt;/li&gt;
&lt;li&gt;Use consistent structure&lt;/li&gt;
&lt;li&gt;Don’t include “why” (link to explanations)&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;When writing explanations&lt;/strong&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Focus on understanding&lt;/li&gt;
&lt;li&gt;Discuss alternatives and trade-offs&lt;/li&gt;
&lt;li&gt;Don’t give step-by-step instructions&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;common-mistakes-to-avoid&quot;&gt;Common Mistakes to Avoid&lt;/h2&gt;
&lt;h3 id=&quot;mixing-types&quot;&gt;Mixing Types&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Bad&lt;/strong&gt; (tutorial mixed with reference):&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;markdown&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82B1FF;--1:#3B61B0&quot;&gt;# Getting Started&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;Run &lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;`spec-kitty init`&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;. This command accepts the following flags:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;--force, --quiet, --verbose, --config=PATH, --mission=TYPE...&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;[100 lines of flag documentation]&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;Good&lt;/strong&gt; (tutorial with link to reference):&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;markdown&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82B1FF;--1:#3B61B0&quot;&gt;# Getting Started&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;Run &lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;`spec-kitty init`&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; to set up your project.&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;For all available options, see the [&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--0td:underline;--1:#403F53;--1td:underline&quot;&gt;CLI Reference&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;]&lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;(&lt;/span&gt;&lt;span style=&quot;--0:#FF869A;--0td:underline;--1:#954F5A;--1td:underline&quot;&gt;../api/cli-commands.md#spec-kitty-init&lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;)&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;.&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;h3 id=&quot;wrong-type-for-user-state&quot;&gt;Wrong Type for User State&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Bad&lt;/strong&gt; (explanation when user needs how-to):&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;markdown&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82B1FF;--1:#3B61B0&quot;&gt;# How to Resolve Merge Conflicts&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;First, let&apos;s understand why merge conflicts occur. When Git&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;encounters changes to the same file from different branches,&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;it cannot automatically determine which changes to keep...&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;[500 words of theory]&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;Good&lt;/strong&gt; (how-to focused on doing):&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;markdown&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82B1FF;--1:#3B61B0&quot;&gt;# How to Resolve Merge Conflicts&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;1.&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; Identify conflicting files: &lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;`git status`&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;2.&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; Open each file and find &lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;`&amp;#x3C;&amp;#x3C;&amp;#x3C;&amp;#x3C;&amp;#x3C;&amp;#x3C;&amp;#x3C;`&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; markers&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;3.&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; Choose which changes to keep&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;4.&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; Remove conflict markers&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;5.&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; Stage and commit: &lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;`git add . &amp;#x26;&amp;#x26; git commit`&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;For background on why conflicts occur, see [&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--0td:underline;--1:#403F53;--1td:underline&quot;&gt;Git Worktrees Explained&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;]&lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;(&lt;/span&gt;&lt;span style=&quot;--0:#FF869A;--0td:underline;--1:#954F5A;--1td:underline&quot;&gt;git-worktrees.md&lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;)&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;.&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;h2 id=&quot;further-reading&quot;&gt;Further Reading&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;https://documentation.divio.com/&quot;&gt;Divio Documentation System&lt;/a&gt; - The original framework&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://www.youtube.com/watch?v=p0PPtdRHG6M&quot;&gt;What nobody tells you about documentation&lt;/a&gt; - Conference talk by Divio’s creator&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;see-also&quot;&gt;See Also&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;/architecture/spec-driven-development/&quot;&gt;Spec-Driven Development&lt;/a&gt; - The methodology behind Spec Kitty&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/architecture/mission-system/&quot;&gt;Mission System&lt;/a&gt; - How different missions produce different documentation&lt;/li&gt;
&lt;/ul&gt;
&lt;hr&gt;
&lt;p&gt;&lt;em&gt;This document explains why we use Divio. For how to write documentation, see the tutorials and how-to guides.&lt;/em&gt;&lt;/p&gt;
&lt;h2 id=&quot;try-it&quot;&gt;Try It&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;/guides/tutorials/claude-code-workflow/&quot;&gt;Claude Code Workflow&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;how-to-guides&quot;&gt;How-To Guides&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;/guides/how-to/installation/install-spec-kitty/&quot;&gt;Install Spec Kitty&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;reference&quot;&gt;Reference&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;/api/configuration/&quot;&gt;Configuration&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/api/file-structure/&quot;&gt;File Structure&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
