PageSourceSearch

https://diataxis.fr/start-here/

html diataxis.fr collected 2026-10-01 11:26:31 UTC 29,865 bytes, 522 lines download raw bytes

1<!doctype html>
2<html class="no-js" lang="en" data-content_root="../">
3  <head>
4  <meta name="author" content="Daniele Procida">
5  <meta charset="utf-8">
6    <meta name="viewport" content="width=device-width,initial-scale=1">
7    <meta name="color-scheme" content="light dark"><meta name="viewport" content="width=device-width, initial-scale=1" />
8<meta content="The best way to get started with Diátaxis is by applying it to documentation problems." name="description" />
9<link rel="alternate" type="application/atom+xml" title="Diátaxis" href="https://diataxis.fr/atom.xml"/><link rel="index" title="Index" href="../genindex/"><link rel="search" title="Search" href="../search/"><link rel="next" title="Applying Diátaxis" href="../application/"><link rel="prev" title="Diátaxis" href="../">
10        <link rel="prefetch" href="../_static/diataxis-white-416.png" as="image">
11
12    <link rel="shortcut icon" href="../_static/favicon.png"><!-- Generated with Sphinx 8.2.3 and Furo 2025.12.19 -->
13  
14        <title>Start here - Diátaxis in five minutes - Diátaxis</title>
15      <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=d111a655" />
16    <link rel="stylesheet" type="text/css" href="../_static/styles/furo.css?v=7bdb33bb" />
17    <link rel="stylesheet" type="text/css" href="../_static/sphinx-design.min.css?v=95c83b7e" />
18    <link rel="stylesheet" type="text/css" href="../_static/styles/furo-extensions.css?v=8dab3a3b" />
19    <link rel="stylesheet" type="text/css" href="../_static/diataxis.css?v=1c871360" />
20    
21    
22
23
24<style>
25  body {
26    --color-code-background: #f2f2f2;
27  --color-code-foreground: #1e1e1e;
28  --color-background-secondary: #fff;
29  --color-sidebar-background-border: none;
30  
31  }
32  @media not print {
33    body[data-theme="dark"] {
34      --color-code-background: #202020;
35  --color-code-foreground: #d0d0d0;
36  --color-background-secondary: #000;
37  
38    }
39    @media (prefers-color-scheme: dark) {
40      body:not([data-theme="light"]) {
41        --color-code-background: #202020;
42  --color-code-foreground: #d0d0d0;
43  --color-background-secondary: #000;
44  
45      }
46    }
47  }
48</style>
49  
50  
50<script async type="text/javascript" src="/_/static/javascript/readthedocs-addons.js"></script>
50<meta name="readthedocs-project-slug" content="documentation-system" /><meta name="readthedocs-version-slug" content="latest" /><meta name="readthedocs-resolver-filename" content="/start-here/" /><meta name="readthedocs-http-status" content="200" /></head>
51  <body>
52    
53    
53<script>
54      document.body.dataset.theme = localStorage.getItem("theme") || "auto";
55    </script>
55
56    
57
58<svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
59  <symbol id="svg-toc" viewBox="0 0 24 24">
60    <title>Contents</title>
61    <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 1024 1024">
62      <path d="M408 442h480c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8H408c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8zm-8 204c0 4.4 3.6 8 8 8h480c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8H408c-4.4 0-8 3.6-8 8v56zm504-486H120c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8h784c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8zm0 632H120c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8h784c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8zM115.4 518.9L271.7 642c5.8 4.6 14.4.5 14.4-6.9V388.9c0-7.4-8.5-11.5-14.4-6.9L115.4 505.1a8.74 8.74 0 0 0 0 13.8z"/>
63    </svg>
64  </symbol>
65  <symbol id="svg-menu" viewBox="0 0 24 24">
66    <title>Menu</title>
67    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
68      stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather-menu">
69      <line x1="3" y1="12" x2="21" y2="12"></line>
70      <line x1="3" y1="6" x2="21" y2="6"></line>
71      <line x1="3" y1="18" x2="21" y2="18"></line>
72    </svg>
73  </symbol>
74  <symbol id="svg-arrow-right" viewBox="0 0 24 24">
75    <title>Expand</title>
76    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
77      stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather-chevron-right">
78      <polyline points="9 18 15 12 9 6"></polyline>
79    </svg>
80  </symbol>
81  <symbol id="svg-sun" viewBox="0 0 24 24">
82    <title>Light mode</title>
83    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
84      stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="feather-sun">
85      <circle cx="12" cy="12" r="5"></circle>
86      <line x1="12" y1="1" x2="12" y2="3"></line>
87      <line x1="12" y1="21" x2="12" y2="23"></line>
88      <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line>
89      <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line>
90      <line x1="1" y1="12" x2="3" y2="12"></line>
91      <line x1="21" y1="12" x2="23" y2="12"></line>
92      <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line>
93      <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line>
94    </svg>
95  </symbol>
96  <symbol id="svg-moon" viewBox="0 0 24 24">
97    <title>Dark mode</title>
98    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
99      stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-moon">
100      <path stroke="none" d="M0 0h24v24H0z" fill="none" />
101      <path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z" />
102    </svg>
103  </symbol>
104  <symbol id="svg-sun-with-moon" viewBox="0 0 24 24">
105    <title>Auto light/dark, in light mode</title>
106    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
107      stroke-width="1" stroke-linecap="round" stroke-linejoin="round"
108      class="icon-custom-derived-from-feather-sun-and-tabler-moon">
109      <path style="opacity: 50%" d="M 5.411 14.504 C 5.471 14.504 5.532 14.504 5.591 14.504 C 3.639 16.319 4.383 19.569 6.931 20.352 C 7.693 20.586 8.512 20.551 9.25 20.252 C 8.023 23.207 4.056 23.725 2.11 21.184 C 0.166 18.642 1.702 14.949 4.874 14.536 C 5.051 14.512 5.231 14.5 5.411 14.5 L 5.411 14.504 Z"/>
110      <line x1="14.5" y1="3.25" x2="14.5" y2="1.25"/>
111      <line x1="14.5" y1="15.85" x2="14.5" y2="17.85"/>
112      <line x1="10.044" y1="5.094" x2="8.63" y2="3.68"/>
113      <line x1="19" y1="14.05" x2="20.414" y2="15.464"/>
114      <line x1="8.2" y1="9.55" x2="6.2" y2="9.55"/>
115      <line x1="20.8" y1="9.55" x2="22.8" y2="9.55"/>
116      <line x1="10.044" y1="14.006" x2="8.63" y2="15.42"/>
117      <line x1="19" y1="5.05" x2="20.414" y2="3.636"/>
118      <circle cx="14.5" cy="9.55" r="3.6"/>
119    </svg>
120  </symbol>
121  <symbol id="svg-moon-with-sun" viewBox="0 0 24 24">
122    <title>Auto light/dark, in dark mode</title>
123    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
124      stroke-width="1" stroke-linecap="round" stroke-linejoin="round"
125      class="icon-custom-derived-from-feather-sun-and-tabler-moon">
126      <path d="M 8.282 7.007 C 8.385 7.007 8.494 7.007 8.595 7.007 C 5.18 10.184 6.481 15.869 10.942 17.24 C 12.275 17.648 13.706 17.589 15 17.066 C 12.851 22.236 5.91 23.143 2.505 18.696 C -0.897 14.249 1.791 7.786 7.342 7.063 C 7.652 7.021 7.965 7 8.282 7 L 8.282 7.007 Z"/>
127      <line style="opacity: 50%" x1="18" y1="3.705" x2="18" y2="2.5"/>
128      <line style="opacity: 50%" x1="18" y1="11.295" x2="18" y2="12.5"/>
129      <line style="opacity: 50%" x1="15.316" y1="4.816" x2="14.464" y2="3.964"/>
130      <line style="opacity: 50%" x1="20.711" y1="10.212" x2="21.563" y2="11.063"/>
131      <line style="opacity: 50%" x1="14.205" y1="7.5" x2="13.001" y2="7.5"/>
132      <line style="opacity: 50%" x1="21.795" y1="7.5" x2="23" y2="7.5"/>
133      <line style="opacity: 50%" x1="15.316" y1="10.184" x2="14.464" y2="11.036"/>
134      <line style="opacity: 50%" x1="20.711" y1="4.789" x2="21.563" y2="3.937"/>
135      <circle style="opacity: 50%" cx="18" cy="7.5" r="2.169"/>
136    </svg>
137  </symbol>
138  <symbol id="svg-pencil" viewBox="0 0 24 24">
139    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
140      stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-pencil-code">
141      <path d="M4 20h4l10.5 -10.5a2.828 2.828 0 1 0 -4 -4l-10.5 10.5v4" />
142      <path d="M13.5 6.5l4 4" />
143      <path d="M20 21l2 -2l-2 -2" />
144      <path d="M17 17l-2 2l2 2" />
145    </svg>
146  </symbol>
147  <symbol id="svg-eye" viewBox="0 0 24 24">
148    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
149      stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-eye-code">
150      <path stroke="none" d="M0 0h24v24H0z" fill="none" />
151      <path d="M10 12a2 2 0 1 0 4 0a2 2 0 0 0 -4 0" />
152      <path
153        d="M11.11 17.958c-3.209 -.307 -5.91 -2.293 -8.11 -5.958c2.4 -4 5.4 -6 9 -6c3.6 0 6.6 2 9 6c-.21 .352 -.427 .688 -.647 1.008" />
154      <path d="M20 21l2 -2l-2 -2" />
155      <path d="M17 17l-2 2l2 2" />
156    </svg>
157  </symbol>
158</svg>
159
160<input type="checkbox" class="sidebar-toggle" name="__navigation" id="__navigation" aria-label="Toggle site navigation sidebar">
161<input type="checkbox" class="sidebar-toggle" name="__toc" id="__toc" aria-label="Toggle table of contents sidebar">
162<label class="overlay sidebar-overlay" for="__navigation"></label>
163<label class="overlay toc-overlay" for="__toc"></label>
164
165<a class="skip-to-content muted-link" href="#furo-main-content">Skip to content</a>
166
167
168
169<div class="page">
170  <header class="mobile-header">
171    <div class="header-left">
172      <label class="nav-overlay-icon" for="__navigation">
173        <span class="icon"><svg><use href="#svg-menu"></use></svg></span>
174      </label>
175    </div>
176    <div class="header-center">
177      <a href="../"><div class="brand">Diátaxis</div></a>
178    </div>
179    <div class="header-right">
180      <div class="theme-toggle-container theme-toggle-header">
181        <button class="theme-toggle" aria-label="Toggle Light / Dark / Auto color theme">
182          <svg class="theme-icon-when-auto-light"><use href="#svg-sun-with-moon"></use></svg>
183          <svg class="theme-icon-when-auto-dark"><use href="#svg-moon-with-sun"></use></svg>
184          <svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg>
185          <svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg>
186        </button>
187      </div>
188      <label class="toc-overlay-icon toc-header-icon" for="__toc">
189        <span class="icon"><svg><use href="#svg-toc"></use></svg></span>
190      </label>
191    </div>
192  </header>
193  <aside class="sidebar-drawer">
194    <div class="sidebar-container">
195      
196      <div class="sidebar-sticky"><div class="sidebar-scroll"><a class="sidebar-brand" href="../">
197  <div class="sidebar-logo-container">
198    <img class="sidebar-logo" src="../_static/diataxis-white-416.png" alt="Logo"/>
199  </div>
200  
201  
202</a><div class="sidebar-tree">
203  <ul>
204<li class="toctree-l1"><a class="reference internal" href="../">Home</a></li>
205</ul>
206<ul class="current">
207<li class="toctree-l1 current current-page"><a class="current reference internal" href="#">Start here</a></li>
208</ul>
209<ul>
210<li class="toctree-l1"><a class="reference internal" href="../application/">Applying Diátaxis</a></li>
211<li class="toctree-l1"><a class="reference internal" href="../tutorials/">Tutorials</a></li>
212<li class="toctree-l1"><a class="reference internal" href="../how-to-guides/">How-to guides</a></li>
213<li class="toctree-l1"><a class="reference internal" href="../reference/">Reference</a></li>
214<li class="toctree-l1"><a class="reference internal" href="../explanation/">Explanation</a></li>
215<li class="toctree-l1"><a class="reference internal" href="../compass/">The compass</a></li>
216<li class="toctree-l1"><a class="reference internal" href="../how-to-use-diataxis/">Workflow</a></li>
217</ul>
218<ul>
219<li class="toctree-l1"><a class="reference internal" href="../theory/">Understanding Diátaxis</a></li>
220<li class="toctree-l1"><a class="reference internal" href="../foundations/">Foundations</a></li>
221<li class="toctree-l1"><a class="reference internal" href="../map/">The map</a></li>
222<li class="toctree-l1"><a class="reference internal" href="../quality/">Quality</a></li>
223<li class="toctree-l1"><a class="reference internal" href="../tutorials-how-to/">Tutorials and how-to guides</a></li>
224<li class="toctree-l1"><a class="reference internal" href="../reference-explanation/">Reference and explanation</a></li>
225</ul>
226<ul>
227<li class="toctree-l1"><a class="reference internal" href="../colophon/">Colophon</a></li>
228<li class="toctree-l1"><a class="reference internal" href="../translation/">Help translate Diátaxis</a></li>
229<li class="toctree-l1"><a class="reference internal" href="../news/">News &amp; Updates</a></li>
230</ul>
231
232</div><form class="sidebar-search-container" method="get" action="../search/" role="search">
233  <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
234  <input type="hidden" name="check_keywords" value="yes">
235  <input type="hidden" name="area" value="default">
236</form>
237<div id="searchbox"></div>
238</div>
239      </div>
240      
241    </div>
242  </aside>
243  <div class="main">
244    <div class="content">
245      <div class="article-container">
246        <a href="#" class="back-to-top muted-link">
247          <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
248            <path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8v12z"></path>
249          </svg>
250          <span>Back to top</span>
251        </a>
252        <div class="content-icon-container">
253          <div class="theme-toggle-container theme-toggle-content">
254            <button class="theme-toggle" aria-label="Toggle Light / Dark / Auto color theme">
255              <svg class="theme-icon-when-auto-light"><use href="#svg-sun-with-moon"></use></svg>
256              <svg class="theme-icon-when-auto-dark"><use href="#svg-moon-with-sun"></use></svg>
257              <svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg>
258              <svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg>
259            </button>
260          </div>
261          <label class="toc-overlay-icon toc-content-icon" for="__toc">
262            <span class="icon"><svg><use href="#svg-toc"></use></svg></span>
263          </label>
264        </div>
265        <article role="main" id="furo-main-content">
266          
267  <nav class="language-switcher" aria-label="Language">
268    <a href="/start-here/" lang="en" aria-current="true">
269      <span class="language-switcher-full-label">English</span>
270      <span class="language-switcher-short-label">EN</span>
271    </a>
272    <a href="/pl/start-here/" lang="pl">
273      <span class="language-switcher-full-label">Polski</span>
274      <span class="language-switcher-short-label">PL</span>
275    </a>
276    
277  </nav>
278  <section id="start-here-diataxis-in-five-minutes">
279<h1>Start here - Diátaxis in five minutes<a class="headerlink" href="#start-here-diataxis-in-five-minutes" title="Link to this heading">¶</a></h1>
280<aside class="sidebar">
281<p>Treat this website as a handbook or a toolbox that you make use of when you need it.</p>
282</aside>
283<p>You don’t need to read everything on this website to make sense of Diátaxis, or to start using it in practice. In fact I recommend that you don’t. <strong>The best way to get started with Diátaxis is by applying it</strong> - to something, however small.</p>
284<p>Read this page for a brief primer. Each section contains links to more in-depth material; refer to that when you need it - when you’re actually at work, or reflecting on the documentation problems you have encountered.</p>
285<hr class="docutils" />
286<section id="the-four-kinds-of-documentation">
287<h2>The four kinds of documentation<a class="headerlink" href="#the-four-kinds-of-documentation" title="Link to this heading">¶</a></h2>
288<p>The core idea of Diátaxis is that there are fundamentally four identifiable kinds of documentation, that respond to four different needs. The four kinds are: <em>tutorials</em>, <em>how-to guides</em>, <em>reference</em> and <em>explanation</em>. Each has a different purpose, and needs to be written in a different way.</p>
289<section id="tutorials">
290<h3>Tutorials<a class="headerlink" href="#tutorials" title="Link to this heading">¶</a></h3>
291<aside class="sidebar">
292<ul class="simple">
293<li><p><a class="reference internal" href="../tutorials/#tutorials"><span class="std std-ref">Tutorials in more detail</span></a></p></li>
294<li><p><a class="reference internal" href="../tutorials-how-to/#tutorials-how-to"><span class="std std-ref">Why tutorials are completely different from how-to guides</span></a></p></li>
295</ul>
296</aside>
297<p><strong>A tutorial is a lesson</strong>, that takes a student by the hand through a learning experience. A tutorial is always <em>practical</em>: the user <em>does</em> something, under the guidance of an instructor. A tutorial is designed around an encounter that the learner can make sense of, in which the instructor is responsible for the learner’s safety and success.</p>
298<p>A driving lesson is a good example of a tutorial. The purpose of the lesson is to develop skills and confidence in the student, not to get from A to B. A software example could be: <em>Let’s create a simple game in Python</em>.</p>
299<p><em>The user will learn through what they do</em> - not because someone has tried to teach them.</p>
300<p>In documentation, the special difficulty is that the instructor is condemned to be absent, and is not there to monitor the learner and correct their mistakes. The instructor must somehow find a way to be present through written instruction alone.</p>
301</section>
302<section id="how-to-guides">
303<h3>How-to guides<a class="headerlink" href="#how-to-guides" title="Link to this heading">¶</a></h3>
304<aside class="sidebar">
305<ul class="simple">
306<li><p><a class="reference internal" href="../how-to-guides/#how-to"><span class="std std-ref">How-to guides in more detail</span></a></p></li>
307</ul>
308</aside>
309<p><strong>A how-to guide addresses a real-world goal or problem</strong>, by providing practical directions to help the user who is in that situation.</p>
310<p>A how-to guide always addresses an already-competent user, who is expected to be able to use the guide to help them get their work done. In contrast to a tutorial, a how-to guide is concerned with <em>work</em> rather than <em>study</em>.</p>
311<p>A how-to guide might be: <em>How to store cellulose nitrate film</em> (in motion picture photography) or <em>How to configure frame profiling</em> (in software). Or even: <em>Troubleshooting deployment problems</em>.</p>
312</section>
313<section id="reference">
314<h3>Reference<a class="headerlink" href="#reference" title="Link to this heading">¶</a></h3>
315<aside class="sidebar">
316<ul class="simple">
317<li><p><a class="reference internal" href="../reference/#reference"><span class="std std-ref">Reference in more detail</span></a></p></li>
318</ul>
319</aside>
320<p><strong>Reference guides contain the technical description</strong> - facts - that a user needs in order to do things correctly: accurate, complete, reliable information, free of distraction and interpretation. They contain <em>propositional or theoretical knowledge</em>, not guides to action.</p>
321<p>Like a how-to guide, reference documentation serves the user who is at <em>work</em>, and it’s up to the user to be sufficiently competent to interpret and use it correctly.</p>
322<p><em>Reference material is neutral.</em> It is not concerned with what the user is doing. A marine chart could be used by a ship’s navigator to plot a course, but equally well by an investigating judge.</p>
323<p>Where possible, the architecture of reference documentation should reflect the structure or architecture of the thing it’s describing - just like a map does. If a method is part of a class that belongs to a certain module, then we should expect to see the same relationship in the documentation too.</p>
324</section>
325<section id="explanation">
326<h3>Explanation<a class="headerlink" href="#explanation" title="Link to this heading">¶</a></h3>
327<aside class="sidebar">
328<ul class="simple">
329<li><p><a class="reference internal" href="../explanation/#explanation"><span class="std std-ref">Explanation in more detail</span></a></p></li>
330<li><p><a class="reference internal" href="../reference-explanation/#reference-explanation"><span class="std std-ref">Understanding the difference between reference and explanation</span></a></p></li>
331</ul>
332</aside>
333<p><strong>Explanatory guides provide context and background.</strong> They serve the need to understand and put things in a bigger picture. Explanation joins things together, and helps answer the question <em>why?</em></p>
334<p>Explanation often needs to circle around its subject, and approach it from different directions. It can contain opinions and take perspectives.</p>
335<p>Like reference, explanation belongs to the realm of propositional knowledge rather than action. However its purpose is to serve the user’s study - as tutorials do - and not their work.</p>
336<p>Often, writers of tutorials who are anxious that their students should <em>know</em> things overload their tutorials with distracting and unhelpful explanation. It would be much more useful to give the learner the most minimal explanation (“Here, we use HTTPS because it’s safer”) and then link to an in-depth article (<em>Secure communication using HTTPS encryption</em>) for when the user is ready for it.</p>
337</section>
338</section>
339<hr class="docutils" />
340<section id="the-diataxis-map">
341<h2>The Diátaxis map<a class="headerlink" href="#the-diataxis-map" title="Link to this heading">¶</a></h2>
342<p>The four kinds of documentation and the relationships between them can be summarised in the Diátaxis map.</p>
343<aside class="sidebar">
344<ul class="simple">
345<li><p><a class="reference internal" href="../map/#map"><span class="std std-ref">The map in more detail</span></a></p></li>
346</ul>
347</aside>
348<p>Diátaxis is not just a list of four different things, but a conceptual arrangement of them. It shows how the four kinds of documentation are related to each other, and distinct from each other.</p>
349<p>
349Crossing or blurring the boundaries described in the map is at the heart of a vast number of problems in documentation.</p>
350<img alt="Diátaxis" src="../_images/diataxis.png" />
351</section>
352<hr class="docutils" />
353<section id="the-diataxis-compass">
354<h2>The Diátaxis compass<a class="headerlink" href="#the-diataxis-compass" title="Link to this heading">¶</a></h2>
355<p>As you can see from the map:</p>
356<ul class="simple">
357<li><p>tutorials and how-to guides are concerned with what the user <em>does</em> (<strong>action</strong>)</p></li>
358<li><p>reference and explanation are about what the user <em>knows</em> (<strong>cognition</strong>)</p></li>
359</ul>
360<p>On the other hand:</p>
361<ul class="simple">
362<li><p>tutorials and explanation serve the <em>acquisition</em> of skill (the user’s <strong>study</strong>)</p></li>
363<li><p>how-to guides and reference serve the <em>application</em> of skill (the user’s <strong>work</strong>)</p></li>
364</ul>
365<p>But a map doesn’t tell you what to <em>do</em> - it’s reference. To guide your action you need a different sort of tool, in this case, a kind of Diátaxis compass.</p>
366<aside class="sidebar">
367<ul class="simple">
368<li><p><a class="reference internal" href="../compass/#compass"><span class="std std-ref">The compass in more detail</span></a></p></li>
369</ul>
370</aside>
371<p>The compass is useful in two different ways.</p>
372<p>When creating documentation, it helps clarify your own intentions, and helps make sure you’re actually doing what you think you’re doing.</p>
373<p>When looking at documentation, it helps understand what’s going on in it, and makes problems stand out.</p>
374<p>The compass is not nearly as eye-catching as the map, but when you’re at work puzzling over a documentation problem it’s what will help you move forward.</p>
375<div class="table-wrapper colwidths-given wider docutils container">
376<table class="wider docutils align-default">
377<colgroup>
378<col style="width: 33.0%" />
379<col style="width: 33.0%" />
380<col style="width: 34.0%" />
381</colgroup>
382<thead>
383<tr class="row-odd"><th class="head"><p>If the content…</p></th>
384<th class="head"><p>…and serves the user’s…</p></th>
385<th class="head"><p>…then it must belong to…</p></th>
386</tr>
387</thead>
388<tbody>
389<tr class="row-even"><td><p>informs action</p></td>
390<td><p>acquisition of skill</p></td>
391<td><p>a tutorial</p></td>
392</tr>
393<tr class="row-odd"><td><p>informs action</p></td>
394<td><p>application of skill</p></td>
395<td><p>a how-to guide</p></td>
396</tr>
397<tr class="row-even"><td><p>informs cognition</p></td>
398<td><p>application of skill</p></td>
399<td><p>reference</p></td>
400</tr>
401<tr class="row-odd"><td><p>informs cognition</p></td>
402<td><p>acquisition of skill</p></td>
403<td><p>explanation</p></td>
404</tr>
405</tbody>
406</table>
407</div>
408</section>
409<hr class="docutils" />
410<section id="working">
411<h2>Working<a class="headerlink" href="#working" title="Link to this heading">¶</a></h2>
412<p>There is a very simple workflow for Diátaxis.</p>
413<aside class="sidebar">
414<p><a class="reference internal" href="../how-to-use-diataxis/#how-to-use-diataxis"><span class="std std-ref">Diátaxis as a guide to work</span></a></p>
415</aside>
416<ol class="arabic simple">
417<li><p>Consider what you see in the documentation, in front of you right now (which might be literally nothing, if you haven’t started yet).</p></li>
418<li><p>Ask: <em>is there any way in which it could be improved?</em></p></li>
419<li><p>Decide on <em>one</em> thing you could do to it right now, however small, that would improve it.</p></li>
420<li><p>Do that thing.</p></li>
421</ol>
422<p>And then repeat.</p>
423<p>That’s it.</p>
424</section>
425<hr class="docutils" />
426<section id="do-what-you-like">
427<h2>Do what you like<a class="headerlink" href="#do-what-you-like" title="Link to this heading">¶</a></h2>
428<p>You can do what you like with Diátaxis. You don’t have to believe in it and there is no exam. It is a wholly pragmatic approach. I think it’s <em>true</em>, but what matters is that it actually helps people create better documentation. If you find one idea or insight in it that seems to be worthwhile, help yourself to that.</p>
429<p>There is an extensively elaborated theory around Diátaxis, but you don’t need to subscribe to it, or even read about it. Diátaxis doesn’t require a commitment to pursue it to a final end.</p>
430<p>You can do just one thing, right now, and even if you do nothing else ever after, you will at least have made that one improvement. (In practice what you will find is that each thing you do will give you a clue as to the next thing to do - you only need to keep doing them.)</p>
431</section>
432<section id="get-started">
433<h2>Get started<a class="headerlink" href="#get-started" title="Link to this heading">¶</a></h2>
434<p>At this point, you have read everything you need to get started with Diátaxis.</p>
435<p>You can read more if you want, and eventually you probably should, but <em>you will get the most value from the guidance in this website when you turn to it with a problem or a question</em>. That’s when it comes alive.</p>
436</section>
437</section>
438
439  
440        </article>
441      </div>
442      <footer>
443        
444  <div class="related-pages">
445    <a class="next-page" href="../application/">
446        <div class="page-info">
447          <div class="context">
448            <span>Next</span>
449          </div>
450          <div class="title">Applying Diátaxis</div>
451        </div>
452        <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
453      </a>
454    <a class="prev-page" href="../">
455        <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
456        <div class="page-info">
457          <div class="context">
458            <span>Previous</span>
459          </div>
460          
461          <div class="title">Home</div>
462          
463        </div>
464      </a>
465  </div>
466  <div class="bottom-of-page">
467    <div class="left-details">
468      <div class="copyright">
469          Copyright &#169; Daniele Procida
470      </div>
471    </div>
472    <div class="right-details">
473      
474    </div>
475  </div>
476  
477      </footer>
478    </div>
479    <aside class="toc-drawer">
480      
481      
482      <div class="toc-sticky toc-scroll">
483        <div class="toc-title-container">
484          <span class="toc-title">
485            On this page
486          </span>
487        </div>
488        <div class="toc-tree-container">
489          <div class="toc-tree">
490            <ul>
491<li><a class="reference internal" href="#">Start here - Diátaxis in five minutes</a><ul>
492<li><a class="reference internal" href="#the-four-kinds-of-documentation">The four kinds of documentation</a><ul>
493<li><a class="reference internal" href="#tutorials">Tutorials</a></li>
494<li><a class="reference internal" href="#how-to-guides">How-to guides</a></li>
495<li><a class="reference internal" href="#reference">Reference</a></li>
496<li><a class="reference internal" href="#explanation">Explanation</a></li>
497</ul>
498</li>
499<li><a class="reference internal" href="#the-diataxis-map">The Diátaxis map</a></li>
500<li><a class="reference internal" href="#the-diataxis-compass">The Diátaxis compass</a></li>
501<li><a class="reference internal" href="#working">Working</a></li>
502<li><a class="reference internal" href="#do-what-you-like">Do what you like</a></li>
503<li><a class="reference internal" href="#get-started">Get started</a></li>
504</ul>
505</li>
506</ul>
507
508          </div>
509        </div>
510      </div>
511      
512      
513    </aside>
514  </div>
515</div>
515<script src="../_static/documentation_options.js?v=187304be"></script>
515
516    
516<script src="../_static/doctools.js?v=9bcbadda"></script>
516
517    
517<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
517
518    
518<script src="../_static/scripts/furo.js?v=46bd48cc"></script>
518
519    
519<script src="../_static/design-tabs.js?v=f930bc37"></script>
519
520    
520<script src="../_static/language-switcher.js?v=9aadebbf"></script>
520
521    </body>
522</html>

Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.