├── .gitignore ├── .readthedocs.yaml ├── CITATION.cff ├── LICENSE.rst ├── Makefile ├── README.rst ├── _static └── diataxis.css ├── _templates └── page.html ├── application.rst ├── colophon.rst ├── compass.rst ├── complex-hierarchies.rst ├── conf.py ├── diataxis.png ├── explanation.rst ├── favicon.png ├── foundations.rst ├── how-to-guides.rst ├── how-to-use-diataxis.rst ├── images ├── acquisition-application.png ├── action-cognition.png ├── always-complete.jpg ├── anselmo.jpg ├── axes-of-needs.png ├── bookshelves.jpg ├── diataxis-white-416.png ├── diataxis-white-original.png ├── diataxis-white.png ├── diataxis.png ├── lasagne.jpg ├── map-movement.png ├── mcgee.jpg ├── old-recipe.jpg ├── operation.jpg ├── overview-explanation.png ├── overview-how-to.png ├── overview-reference.png ├── overview-tutorials.png ├── partial-collapse.png ├── suture.jpg ├── total-collapse.png ├── two-dimensions.png └── wheat.jpg ├── index.rst ├── make.bat ├── map.rst ├── quality.rst ├── reference-explanation.rst ├── reference.rst ├── requirements.txt ├── spelling_wordlist.txt ├── start-here.rst ├── theory.rst ├── tutorials-how-to.rst └── tutorials.rst /.gitignore: -------------------------------------------------------------------------------- 1 | /*env*/ 2 | _build 3 | .DS_Store 4 | __pycache__ 5 | .idea/ 6 | stashed/ 7 | -------------------------------------------------------------------------------- /.readthedocs.yaml: -------------------------------------------------------------------------------- 1 | # .readthedocs.yaml 2 | # Read the Docs configuration file 3 | # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details 4 | 5 | # Required 6 | version: 2 7 | 8 | # Set the version of Python and other tools you might need 9 | build: 10 | os: ubuntu-22.04 11 | tools: 12 | python: "3.11" 13 | 14 | # Build documentation in the docs/ directory with Sphinx 15 | sphinx: 16 | configuration: conf.py 17 | builder: "dirhtml" 18 | 19 | # We recommend specifying your dependencies to enable reproducible builds: 20 | # https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html 21 | python: 22 | install: 23 | - requirements: requirements.txt 24 | 25 | formats: 26 | - pdf 27 | -------------------------------------------------------------------------------- /CITATION.cff: -------------------------------------------------------------------------------- 1 | # This CITATION.cff file was generated with cffinit. 2 | # Visit https://bit.ly/cffinit to generate yours today! 3 | 4 | cff-version: 1.2.0 5 | title: Diátaxis documentation framework 6 | message: >- 7 | Please cite this software using the metadata from 'preferred-citation' 8 | type: software 9 | authors: 10 | - email: daniele@vurt.org 11 | orcid: 'https://orcid.org/0000-0001-5141-7509' 12 | given-names: Daniele 13 | family-names: Procida 14 | preferred-citation: 15 | type: generic 16 | authors: 17 | - given-names: Daniele 18 | family-names: Procida 19 | orcid: 'https://orcid.org/0000-0001-5141-7509' 20 | title: Diátaxis documentation framework 21 | url: "https://diataxis.fr/" 22 | 23 | -------------------------------------------------------------------------------- /LICENSE.rst: -------------------------------------------------------------------------------- 1 | Creative Commons Attribution-ShareAlike 4.0 International 2 | ========================================================= 3 | 4 | Creative Commons Corporation (“Creative Commons”) is not a law firm and does not provide legal services or legal advice. Distribution of Creative Commons public licenses does not create a lawyer-client or other relationship. Creative Commons makes its licenses and related information available on an “as-is” basis. Creative Commons gives no warranties regarding its licenses, any material licensed under their terms and conditions, or any related information. Creative Commons disclaims all liability for damages resulting from their use to the fullest extent possible. 5 | 6 | Using Creative Commons Public Licenses 7 | -------------------------------------- 8 | 9 | Creative Commons public licenses provide a standard set of terms and conditions that creators and other rights holders may use to share original works of authorship and other material subject to copyright and certain other rights specified in the public license below. The following considerations are for informational purposes only, are not exhaustive, and do not form part of our licenses. 10 | 11 | - **Considerations for licensors:** Our public licenses are intended for use by those authorized to give the public permission to use material in ways otherwise restricted by copyright and certain other rights. Our licenses are irrevocable. Licensors should read and understand the terms and conditions of the license they choose before applying it. Licensors should also secure all rights necessary before applying our licenses so that the public can reuse the material as expected. Licensors should clearly mark any material not subject to the license. This includes other CC-licensed material, or material used under an exception or limitation to copyright. `More considerations for licensors `_. 12 | 13 | - **Considerations for the public:** By using one of our public licenses, a licensor grants the public permission to use the licensed material under specified terms and conditions. If the licensor’s permission is not necessary for any reason–for example, because of any applicable exception or limitation to copyright–then that use is not regulated by the license. Our licenses grant only permissions under copyright and certain other rights that a licensor has authority to grant. Use of the licensed material may still be restricted for other reasons, including because others have copyright or other rights in the material. A licensor may make special requests, such as asking that all changes be marked or described. Although not required by our licenses, you are encouraged to respect those requests where reasonable. `More considerations for the public `_. 14 | 15 | Creative Commons Attribution-ShareAlike 4.0 International Public License 16 | ======================================================================== 17 | 18 | By exercising the Licensed Rights (defined below), You accept and agree to be bound by the terms and conditions of this Creative Commons Attribution-ShareAlike 4.0 International Public License ("Public License"). To the extent this Public License may be interpreted as a contract, You are granted the Licensed Rights in consideration of Your acceptance of these terms and conditions, and the Licensor grants You such rights in consideration of benefits the Licensor receives from making the Licensed Material available under these terms and conditions. 19 | 20 | Section 1 – Definitions. 21 | ------------------------ 22 | 23 | a. **Adapted Material** means material subject to Copyright and Similar Rights that is derived from or based upon the Licensed Material and in which the Licensed Material is translated, altered, arranged, transformed, or otherwise modified in a manner requiring permission under the Copyright and Similar Rights held by the Licensor. For purposes of this Public License, where the Licensed Material is a musical work, performance, or sound recording, Adapted Material is always produced where the Licensed Material is synched in timed relation with a moving image. 24 | 25 | b. **Adapter's License** means the license You apply to Your Copyright and Similar Rights in Your contributions to Adapted Material in accordance with the terms and conditions of this Public License. 26 | 27 | c. **BY-SA Compatible License** means a license listed at [creativecommons.org/compatiblelicenses](http://creativecommons.org/compatiblelicenses), approved by Creative Commons as essentially the equivalent of this Public License. 28 | 29 | d. **Copyright and Similar Rights** means copyright and/or similar rights closely related to copyright including, without limitation, performance, broadcast, sound recording, and Sui Generis Database Rights, without regard to how the rights are labeled or categorized. For purposes of this Public License, the rights specified in Section 2(b)(1)-(2) are not Copyright and Similar Rights. 30 | 31 | e. **Effective Technological Measures** means those measures that, in the absence of proper authority, may not be circumvented under laws fulfilling obligations under Article 11 of the WIPO Copyright Treaty adopted on December 20, 1996, and/or similar international agreements. 32 | 33 | f. **Exceptions and Limitations** means fair use, fair dealing, and/or any other exception or limitation to Copyright and Similar Rights that applies to Your use of the Licensed Material. 34 | 35 | g. **License Elements** means the license attributes listed in the name of a Creative Commons Public License. The License Elements of this Public License are Attribution and ShareAlike. 36 | 37 | h. **Licensed Material** means the artistic or literary work, database, or other material to which the Licensor applied this Public License. 38 | 39 | i. **Licensed Rights** means the rights granted to You subject to the terms and conditions of this Public License, which are limited to all Copyright and Similar Rights that apply to Your use of the Licensed Material and that the Licensor has authority to license. 40 | 41 | j. **Licensor** means the individual(s) or entity(ies) granting rights under this Public License. 42 | 43 | k. **Share** means to provide material to the public by any means or process that requires permission under the Licensed Rights, such as reproduction, public display, public performance, distribution, dissemination, communication, or importation, and to make material available to the public including in ways that members of the public may access the material from a place and at a time individually chosen by them. 44 | 45 | l. **Sui Generis Database Rights** means rights other than copyright resulting from Directive 96/9/EC of the European Parliament and of the Council of 11 March 1996 on the legal protection of databases, as amended and/or succeeded, as well as other essentially equivalent rights anywhere in the world. 46 | 47 | m. **You** means the individual or entity exercising the Licensed Rights under this Public License. **Your** has a corresponding meaning. 48 | 49 | Section 2 – Scope. 50 | ------------------ 51 | 52 | a. **License grant.** 53 | 54 | 1. Subject to the terms and conditions of this Public License, the Licensor hereby grants You a worldwide, royalty-free, non-sublicensable, non-exclusive, irrevocable license to exercise the Licensed Rights in the Licensed Material to: 55 | 56 | A. reproduce and Share the Licensed Material, in whole or in part; and 57 | 58 | B. produce, reproduce, and Share Adapted Material. 59 | 60 | 2. **Exceptions and Limitations.** For the avoidance of doubt, where Exceptions and Limitations apply to Your use, this Public License does not apply, and You do not need to comply with its terms and conditions. 61 | 62 | 3. **Term.** The term of this Public License is specified in Section 6(a). 63 | 64 | 4. **Media and formats; technical modifications allowed.** The Licensor authorizes You to exercise the Licensed Rights in all media and formats whether now known or hereafter created, and to make technical modifications necessary to do so. The Licensor waives and/or agrees not to assert any right or authority to forbid You from making technical modifications necessary to exercise the Licensed Rights, including technical modifications necessary to circumvent Effective Technological Measures. For purposes of this Public License, simply making modifications authorized by this Section 2(a)(4) never produces Adapted Material. 65 | 66 | 5. **Downstream recipients.** 67 | 68 | A. **Offer from the Licensor – Licensed Material.** Every recipient of the Licensed Material automatically receives an offer from the Licensor to exercise the Licensed Rights under the terms and conditions of this Public License. 69 | 70 | B. **Additional offer from the Licensor – Adapted Material.** Every recipient of Adapted Material from You automatically receives an offer from the Licensor to exercise the Licensed Rights in the Adapted Material under the conditions of the Adapter’s License You apply. 71 | 72 | C. **No downstream restrictions.** You may not offer or impose any additional or different terms or conditions on, or apply any Effective Technological Measures to, the Licensed Material if doing so restricts exercise of the Licensed Rights by any recipient of the Licensed Material. 73 | 74 | 6. **No endorsement.** Nothing in this Public License constitutes or may be construed as permission to assert or imply that You are, or that Your use of the Licensed Material is, connected with, or sponsored, endorsed, or granted official status by, the Licensor or others designated to receive attribution as provided in Section 3(a)(1)(A)(i). 75 | 76 | b. **Other rights.** 77 | 78 | 1. Moral rights, such as the right of integrity, are not licensed under this Public License, nor are publicity, privacy, and/or other similar personality rights; however, to the extent possible, the Licensor waives and/or agrees not to assert any such rights held by the Licensor to the limited extent necessary to allow You to exercise the Licensed Rights, but not otherwise. 79 | 80 | 2. Patent and trademark rights are not licensed under this Public License. 81 | 82 | 3. To the extent possible, the Licensor waives any right to collect royalties from You for the exercise of the Licensed Rights, whether directly or through a collecting society under any voluntary or waivable statutory or compulsory licensing scheme. In all other cases the Licensor expressly reserves any right to collect such royalties. 83 | 84 | Section 3 – License Conditions. 85 | ------------------------------- 86 | 87 | Your exercise of the Licensed Rights is expressly made subject to the following conditions. 88 | 89 | a. **Attribution.** 90 | 91 | 1. If You Share the Licensed Material (including in modified form), You must: 92 | 93 | A. retain the following if it is supplied by the Licensor with the Licensed Material: 94 | 95 | i. identification of the creator(s) of the Licensed Material and any others designated to receive attribution, in any reasonable manner requested by the Licensor (including by pseudonym if designated); 96 | 97 | ii. a copyright notice; 98 | 99 | iii. a notice that refers to this Public License; 100 | 101 | iv. a notice that refers to the disclaimer of warranties; 102 | 103 | v. a URI or hyperlink to the Licensed Material to the extent reasonably practicable; 104 | 105 | B. indicate if You modified the Licensed Material and retain an indication of any previous modifications; and 106 | 107 | C. indicate the Licensed Material is licensed under this Public License, and include the text of, or the URI or hyperlink to, this Public License. 108 | 109 | 2. You may satisfy the conditions in Section 3(a)(1) in any reasonable manner based on the medium, means, and context in which You Share the Licensed Material. For example, it may be reasonable to satisfy the conditions by providing a URI or hyperlink to a resource that includes the required information. 110 | 111 | 3. If requested by the Licensor, You must remove any of the information required by Section 3(a)(1)(A) to the extent reasonably practicable. 112 | 113 | b. **ShareAlike.** 114 | 115 | In addition to the conditions in Section 3(a), if You Share Adapted Material You produce, the following conditions also apply. 116 | 117 | 1. The Adapter’s License You apply must be a Creative Commons license with the same License Elements, this version or later, or a BY-SA Compatible License. 118 | 119 | 2. You must include the text of, or the URI or hyperlink to, the Adapter's License You apply. You may satisfy this condition in any reasonable manner based on the medium, means, and context in which You Share Adapted Material. 120 | 121 | 3. You may not offer or impose any additional or different terms or conditions on, or apply any Effective Technological Measures to, Adapted Material that restrict exercise of the rights granted under the Adapter's License You apply. 122 | 123 | Section 4 – Sui Generis Database Rights. 124 | ---------------------------------------- 125 | 126 | Where the Licensed Rights include Sui Generis Database Rights that apply to Your use of the Licensed Material: 127 | 128 | a. for the avoidance of doubt, Section 2(a)(1) grants You the right to extract, reuse, reproduce, and Share all or a substantial portion of the contents of the database; 129 | 130 | b. if You include all or a substantial portion of the database contents in a database in which You have Sui Generis Database Rights, then the database in which You have Sui Generis Database Rights (but not its individual contents) is Adapted Material, including for purposes of Section 3(b); and 131 | 132 | c. You must comply with the conditions in Section 3(a) if You Share all or a substantial portion of the contents of the database. 133 | 134 | For the avoidance of doubt, this Section 4 supplements and does not replace Your obligations under this Public License where the Licensed Rights include other Copyright and Similar Rights. 135 | 136 | Section 5 – Disclaimer of Warranties and Limitation of Liability. 137 | ----------------------------------------------------------------- 138 | 139 | a. **Unless otherwise separately undertaken by the Licensor, to the extent possible, the Licensor offers the Licensed Material as-is and as-available, and makes no representations or warranties of any kind concerning the Licensed Material, whether express, implied, statutory, or other. This includes, without limitation, warranties of title, merchantability, fitness for a particular purpose, non-infringement, absence of latent or other defects, accuracy, or the presence or absence of errors, whether or not known or discoverable. Where disclaimers of warranties are not allowed in full or in part, this disclaimer may not apply to You.** 140 | 141 | b. **To the extent possible, in no event will the Licensor be liable to You on any legal theory (including, without limitation, negligence) or otherwise for any direct, special, indirect, incidental, consequential, punitive, exemplary, or other losses, costs, expenses, or damages arising out of this Public License or use of the Licensed Material, even if the Licensor has been advised of the possibility of such losses, costs, expenses, or damages. Where a limitation of liability is not allowed in full or in part, this limitation may not apply to You.** 142 | 143 | c. The disclaimer of warranties and limitation of liability provided above shall be interpreted in a manner that, to the extent possible, most closely approximates an absolute disclaimer and waiver of all liability. 144 | 145 | Section 6 – Term and Termination. 146 | --------------------------------- 147 | 148 | a. This Public License applies for the term of the Copyright and Similar Rights licensed here. However, if You fail to comply with this Public License, then Your rights under this Public License terminate automatically. 149 | 150 | b. Where Your right to use the Licensed Material has terminated under Section 6(a), it reinstates: 151 | 152 | 1. automatically as of the date the violation is cured, provided it is cured within 30 days of Your discovery of the violation; or 153 | 154 | 2. upon express reinstatement by the Licensor. 155 | 156 | For the avoidance of doubt, this Section 6(b) does not affect any right the Licensor may have to seek remedies for Your violations of this Public License. 157 | 158 | c. For the avoidance of doubt, the Licensor may also offer the Licensed Material under separate terms or conditions or stop distributing the Licensed Material at any time; however, doing so will not terminate this Public License. 159 | 160 | d. Sections 1, 5, 6, 7, and 8 survive termination of this Public License. 161 | 162 | Section 7 – Other Terms and Conditions. 163 | --------------------------------------- 164 | 165 | a. The Licensor shall not be bound by any additional or different terms or conditions communicated by You unless expressly agreed. 166 | 167 | b. Any arrangements, understandings, or agreements regarding the Licensed Material not stated herein are separate from and independent of the terms and conditions of this Public License.t stated herein are separate from and independent of the terms and conditions of this Public License. 168 | 169 | Section 8 – Interpretation. 170 | --------------------------- 171 | 172 | a. For the avoidance of doubt, this Public License does not, and shall not be interpreted to, reduce, limit, restrict, or impose conditions on any use of the Licensed Material that could lawfully be made without permission under this Public License. 173 | 174 | b. To the extent possible, if any provision of this Public License is deemed unenforceable, it shall be automatically reformed to the minimum extent necessary to make it enforceable. If the provision cannot be reformed, it shall be severed from this Public License without affecting the enforceability of the remaining terms and conditions. 175 | 176 | c. No term or condition of this Public License will be waived and no failure to comply consented to unless expressly agreed to by the Licensor. 177 | 178 | d. Nothing in this Public License constitutes or may be interpreted as a limitation upon, or waiver of, any privileges and immunities that apply to the Licensor or You, including from the legal processes of any jurisdiction or authority. 179 | 180 | ``Creative Commons is not a party to its public licenses. Notwithstanding, Creative Commons may elect to apply one of its public licenses to material it publishes and in those instances will be considered the “Licensor.” Except for the limited purpose of indicating that material is shared under a Creative Commons public license or as otherwise permitted by the Creative Commons policies published at creativecommons.org/policies, Creative Commons does not authorize the use of the trademark “Creative Commons” or any other trademark or logo of Creative Commons without its prior written consent including, without limitation, in connection with any unauthorized modifications to any of its public licenses or any other arrangements, understandings, or agreements concerning use of licensed material. For the avoidance of doubt, this paragraph does not form part of the public licenses.`` 181 | 182 | ``Creative Commons may be contacted at creativecommons.org.`` 183 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | # You can set these variables from the command line. 2 | SPHINXOPTS = 3 | SPHINXBUILD = sphinx-build 4 | SPHINXPROJ = DocumentationSystem 5 | SOURCEDIR = . 6 | BUILDDIR = _build 7 | 8 | VENV = env/bin/activate 9 | PORT = 8090 10 | 11 | # Put it first so that "make" without argument is like "make help". 12 | help: 13 | @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 14 | 15 | install: 16 | @echo "... setting up virtualenv" 17 | python3 -m venv env 18 | . $(VENV); pip install --upgrade -r requirements.txt 19 | @echo "\n" \ 20 | "--------------------------------------------------------------- \n" \ 21 | "* watch, build and serve the documentation: make run \n" \ 22 | "* check spelling: make spelling \n" \ 23 | "\n" \ 24 | "enchant must be installed in order for pyenchant (and therefore \n" \ 25 | "spelling checks) to work. \n" \ 26 | "--------------------------------------------------------------- \n" 27 | 28 | clean: 29 | -rm -rf _build/* 30 | 31 | run: 32 | . $(VENV); sphinx-autobuild $(ALLSPHINXOPTS) --ignore ".git/*" --ignore "*.scss" . -b dirhtml -a _build/html --host 0.0.0.0 --port $(PORT) 33 | 34 | test: 35 | . $(VENV); $(SPHINXBUILD) -b html . _build/html 36 | 37 | html: 38 | . $(VENV); $(SPHINXBUILD) -b html . _build/html 39 | 40 | spelling: 41 | . $(VENV); $(SPHINXBUILD) -b spelling $(ALLSPHINXOPTS) . _build/spelling 42 | @echo 43 | @echo "Check finished. Wrong words can be found in " \ 44 | "_build/spelling/output.txt." 45 | 46 | quickstart: 47 | . $(VENV); sphinx-quickstart 48 | 49 | .PHONY: help install clean run Makefile 50 | 51 | # Catch-all target: route all unknown targets to Sphinx using the new 52 | # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). 53 | %: Makefile 54 | @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 55 | -------------------------------------------------------------------------------- /README.rst: -------------------------------------------------------------------------------- 1 | The documentation system 2 | ======================== 3 | 4 | A comprehensive and practical system that can help maintainers of product documentation. 5 | 6 | Published at https://diataxis.fr 7 | 8 | Author: Daniele Procida 9 | 10 | License: `CC-BY-SA 4.0 `_ 11 | -------------------------------------------------------------------------------- /_static/diataxis.css: -------------------------------------------------------------------------------- 1 | @import url('https://fonts.googleapis.com/css2?family=Source+Sans+3:ital,wght@0,400;0,700;1,400;1,700&family=Source+Serif+4:ital,opsz,wght@0,8..60,400;0,8..60,700;1,8..60,400;1,8..60,700&display=swap'); 2 | 3 | 4 | :root { 5 | --orange: #FF9300; 6 | } 7 | 8 | body {font-family: 'Source Serif 4', serif;} 9 | aside, table {font-family: 'Source Sans 3', sans-serif;} 10 | 11 | 12 | /* --------- headings --------- */ 13 | 14 | h1 {font-size: 2rem;} 15 | 16 | h2 { 17 | font-weight: 700; 18 | font-size: 1.75rem; 19 | } 20 | 21 | h3 { 22 | font-weight: 400; 23 | font-size: 1.75rem; 24 | } 25 | 26 | /* --------- left and right TOCs --------- */ 27 | 28 | .sidebar-drawer { 29 | width: calc(50% - 28em); 30 | min-width: 13em; 31 | justify-content: space-around; 32 | } 33 | .sidebar-container, .toc-drawer { 34 | width: 12em; 35 | } 36 | 37 | div.sidebar-tree .toctree-l1.current-page>.reference {color: var(--orange); font-weight: normal;} 38 | div.sidebar-tree .toctree-l1>.reference {color: #666; padding: .3rem .5rem} 39 | div.sidebar-tree .toctree-l1>.reference:hover {color: var(--orange);} 40 | div.sidebar-tree .toctree-l1:first-child>.reference {font-weight: bold;} 41 | 42 | div.sidebar-tree ul { 43 | border-bottom: 1px solid var(--orange); 44 | padding: 1em 0; 45 | } 46 | 47 | input.sidebar-search {border: none;} 48 | 49 | /* --------- in-page TOCs --------- */ 50 | 51 | .toc-with-header ul li:first-child {font-weight: bold;} 52 | 53 | 54 | /* --------- asides --------- */ 55 | 56 | article .sidebar { 57 | width: 100%; 58 | position: relative; 59 | float: none; 60 | margin: 2em 0; 61 | background: none; border: none; 62 | } 63 | article aside.sidebar { 64 | border: 1px solid #999; 65 | border-left: 2px solid #999; 66 | border-radius: 0; 67 | } 68 | article .sidebar>* { 69 | font-size: 90%; 70 | border: none 71 | } 72 | article .sidebar p.sidebar-title { 73 | font-weight: 700; 74 | } 75 | 76 | /* --------- widths at different breakpoints --------- */ 77 | /* break out content asides and images at 52em */ 78 | 79 | @media only screen and (min-width: 52em) { 80 | .content { 81 | position: relative; 82 | padding: 0 1em 0 15em; 83 | width: 36em; 84 | } 85 | 86 | article .sidebar, 87 | h2 { 88 | position: absolute; left: 0; 89 | width: 12rem; 90 | margin: -2rem 2rem 0 1rem; 91 | padding-top: 2rem; 92 | padding-right: 0; 93 | padding-left: 0; 94 | text-align: right; 95 | background: none; 96 | } 97 | 98 | article aside.sidebar {border: none;} 99 | article .sidebar>*, 100 | article .sidebar .sidebar-title {padding-left: 0; padding-right: 0;} 101 | img.wider, table.wider, figure.wider { 102 | width: 50em; max-width: 50em; 103 | margin: 2em 0; 104 | left: -14em; 105 | position: relative; 106 | } 107 | 108 | article .sidebar>ol, article .sidebar>ul {text-align: left; padding-left: 1.2rem;} 109 | img.floated { 110 | width: 50%; 111 | float: right; 112 | margin-bottom: 1rem; margin-left: 1rem; 113 | } 114 | 115 | h2>.headerlink, 116 | .sidebar p .headerlink { 117 | position: absolute; top: 0; right: 0; 118 | } 119 | 120 | h2 + * {margin-top: 2rem;} 121 | } 122 | 123 | /* --------- even more space at 67em --------- */ 124 | 125 | @media only screen and (min-width: 67em) { 126 | .content {padding: 0 1em 0 17em;} 127 | article .sidebar, 128 | h2 {width: 14rem;} 129 | img.wider, table.wider, figure.wider { 130 | width: 52em; max-width: 52em; 131 | margin: 2em 0; 132 | left: -16em; 133 | position: relative; 134 | } 135 | } 136 | 137 | @media only screen and (min-width: 82em) { 138 | .content {padding: 0 3em 0 17em;} 139 | } 140 | 141 | 142 | /* --------- misc --------- */ 143 | 144 | p.rubric { 145 | text-transform: none; 146 | font-style: italic; 147 | font-weight: 400; 148 | font-size: 110%; 149 | } 150 | 151 | hr.docutils {background-color: var(--orange);} 152 | 153 | blockquote {font-size: 90%} 154 | blockquote.epigraph { 155 | border-left: none; 156 | padding: 1em 3em 1em 3em; 157 | } 158 | blockquote p.attribution {padding-left: 3em; font-style: normal;} 159 | 160 | figcaption {text-align: right; font-style: italic;} 161 | 162 | div.lined div.sd-col:nth-child(2n) {border-bottom: 1px solid var(--orange);} 163 | 164 | @media only screen and (min-width: 36em) { 165 | div.lined div.sd-col {border-bottom: 1px solid var(--orange);} 166 | } 167 | 168 | 169 | 170 | /* --------- embed --------- */ 171 | 172 | .embed-responsive { 173 | position: relative; 174 | width: 100%; 175 | } 176 | .embed-responsive:before { 177 | display: block; 178 | content: ""; 179 | } 180 | .embed-responsive-item, 181 | .embed-responsive iframe { 182 | position: absolute; 183 | top: 0; 184 | left: 0; 185 | width: 100%; 186 | height: 100%; 187 | } 188 | .embed-responsive-16by9::before { 189 | padding-top: 56.25%; 190 | } 191 | .embed-responsive-4by3::before { 192 | padding-top: 75%; 193 | } 194 | 195 | /* --------- furniture --------- */ 196 | 197 | .nav-overlay-icon .icon svg, .toc-overlay-icon .icon svg, .theme-toggle svg {color: var(--orange);} 198 | 199 | .toc-tree li.scroll-current>.reference {color: var(--orange);} 200 | 201 | /* --------- tables --------- */ 202 | 203 | .table-wrapper {overflow-x: visible;} 204 | table.docutils {box-shadow: none;} 205 | table.docutils th.head {padding: .5rem 0;} 206 | table.docutils td, table.docutils th {border-right: 1px solid var(--orange);} 207 | table.docutils th.stub {text-align: right;} 208 | table.docutils tr:last-child td, 209 | table.docutils tr:last-child th {border-bottom: none;} 210 | table.docutils thead {border-bottom: 1px solid var(--orange);} 211 | table.align-default {margin-left: 0; margin-right: 0} 212 | 213 | /* --------- lists --------- */ 214 | 215 | dl dt {font-style: italic} 216 | 217 | /* --------- links --------- */ 218 | 219 | a:link, a:visited {color: var(--orange);} 220 | 221 | a.headerlink {text-decoration: none;} 222 | 223 | .related-pages a:hover .page-info .title {color: var(--orange);} -------------------------------------------------------------------------------- /_templates/page.html: -------------------------------------------------------------------------------- 1 | {% extends "furo/page.html" %} 2 | 3 | {% block site_meta %} 4 | 5 | {{ super() }} 6 | {% endblock %} 7 | 8 | {% block footer %} 9 |
10 | {% if next -%} 11 | 12 |
13 |
14 | {{ _("Next") }} 15 |
16 |
{{ next.title }}
17 |
18 | 19 | 20 | {%- endif %} 21 | {% if prev -%} 22 | 23 | 24 |
25 |
26 | {{ _("Previous") }} 27 |
28 | {% if prev.link == pathto(master_doc) %} 29 |
{{ _("Home") }}
30 | {% else %} 31 |
{{ prev.title }}
32 | {% endif %} 33 |
34 | 35 | {%- endif %} 36 |
37 |
38 |
39 | {%- if show_copyright %} 40 |
41 | {%- if hasdoc('copyright') %} 42 | {% trans path=pathto('copyright'), copyright=copyright|e -%} 43 | Copyright © {{ copyright }} 44 | {%- endtrans %} 45 | {%- else %} 46 | {% trans copyright=copyright|e -%} 47 | Copyright © {{ copyright }} 48 | {%- endtrans %} 49 | {%- endif %} 50 |
51 | {%- endif %} 52 | 53 | {%- if last_updated -%} 54 |
55 | {% trans last_updated=last_updated|e -%} 56 | Last updated on {{ last_updated }} 57 | {%- endtrans -%} 58 |
59 | {%- endif %} 60 |
61 |
62 | {% if theme_footer_icons or READTHEDOCS -%} 63 |
64 | {% if theme_footer_icons -%} 65 | {% for icon_dict in theme_footer_icons -%} 66 | 67 | {{- icon_dict.html -}} 68 | 69 | {% endfor %} 70 | {%- else -%} 71 | {#- Show Read the Docs project -#} 72 | {%- if READTHEDOCS and slug -%} 73 | 74 | 75 | 76 | 77 | 78 | {%- endif -%} 79 | {#- Show GitHub repository home -#} 80 | {%- if READTHEDOCS and display_github and github_user != "None" and github_repo != "None" -%} 81 | 82 | 83 | 84 | 85 | 86 | {%- endif -%} 87 | {%- endif %} 88 |
89 | {%- endif %} 90 |
91 |
92 | {% endblock footer %} -------------------------------------------------------------------------------- /application.rst: -------------------------------------------------------------------------------- 1 | Applying Diátaxis 2 | ================= 3 | 4 | 5 | The pages in this section are concerned with putting Diátaxis into practice. 6 | 7 | .. sidebar:: 8 | 9 | Diátaxis is underpinned by :doc:`systematic theoretical principles `, but understanding them is not necessary to make effective use of the system. 10 | 11 | Diátaxis is primarily intended as a pragmatic approach for people working on documentation. Most of the key principles required to put it into practice successfully can be grasped intuitively. 12 | 13 | Don't wait to understand Diátaxis before you start trying to put it into practice. Not only do you not need to understand it all to make use of it, you will not understand it until you have started using it (this itself is a Diátaxis principle). 14 | 15 | As soon as you feel you have picked up an idea that seems worth applying to your work, try applying it. Come back here when you need more clarity or reassurance. Iterate between your work and reflecting on your work. 16 | 17 | ---------------- 18 | 19 | In this section 20 | ---------------- 21 | 22 | At the core of Diátaxis are the four different kinds of documentation it identifies. If you're encountering Diátaxis for the first time, start with these pages. 23 | 24 | * :doc:`tutorials` - learning-oriented experiences 25 | * :doc:`how-to-guides` - goal-oriented directions 26 | * :doc:`reference` - information-oriented technical description 27 | * :doc:`explanation` - understanding-oriented discussion 28 | 29 | Diátaxis prescribes principles that guide action. These translate into particular ways of working, with implications for documentation process and execution. Once you've made your first start, the tools and methods outlined here will help smooth your way. 30 | 31 | * :doc:`compass` - a simple tool for direction-finding 32 | * :doc:`Workflow ` in Diátaxis 33 | -------------------------------------------------------------------------------- /colophon.rst: -------------------------------------------------------------------------------- 1 | Colophon 2 | ======== 3 | 4 | Diátaxis is the work of `Daniele Procida `_. 5 | 6 | It has been developed over a number of years, and continues to be elaborated and explored. 7 | 8 | 9 | .. _contact: 10 | 11 | Contact me 12 | ---------- 13 | 14 | `Email me `_. I enjoy hearing about other people's experiences with Diátaxis and read everything I receive. 15 | 16 | I appreciate all the interest and do my best to reply, but I get a considerable quantity of email related to Diátaxis and I can't promise to respond to every message. 17 | 18 | If you'd like to discuss Diátaxis with other users, please see the *#diataxis* channel on the 19 | `Write the Docs Slack group `_, or the `Discussions 20 | `_ section of the `GitHub 21 | repository for this website `_. 22 | 23 | 24 | Origins and development 25 | ----------------------- 26 | 27 | You can find `an earlier presentation of some of these ideas `_, that I created while working at Divio between 2014-2021. I still agree with most of it, though there are several aspects that I now think I got wrong. 28 | 29 | The original context for the Diátaxis approach was limited to software product documentation. 30 | 31 | In 2021 I was awarded a Fellowship of the `Software Sustainability Institute `_, to explore its application in scientific research contexts. More recently I've explored its application in internal corporate documentation, organisational management and education, and also its application at scale. This work is on-going. 32 | 33 | Other people have corresponded with me to share their experience of applying Diátaxis to note-taking systems and even as part of a systematic approach to household management. 34 | 35 | 36 | Citation and contribution 37 | ------------------------- 38 | 39 | To cite Diátaxis, please refer to :doc:`this website, diataxis.fr `. 40 | 41 | The Git repository for the source material contains a citation file, `CITATION.cff 42 | `_. 43 | 44 | APA and BibTeX metadata are available from the *Cite this repository* option at 45 | https://github.com/evildmp/diataxis-documentation-framework. 46 | 47 | You can also submit a pull request to suggest an improvement or correction, or `file an issue 48 | `_. 49 | 50 | Diátaxis is now used in several hundred projects and it is no longer possible for me to keep up with requests to have projects listed here as examples of Diátaxis adoption. 51 | 52 | 53 | Website 54 | ------- 55 | 56 | This website is built with `Sphinx `_ and hosted on `Read the Docs `_, using a modified version of `Pradyun Gedam `_'s `Furo `_ theme. 57 | -------------------------------------------------------------------------------- /compass.rst: -------------------------------------------------------------------------------- 1 | .. _compass: 2 | 3 | The compass 4 | ======================= 5 | 6 | .. image:: /images/diataxis.png 7 | :alt: 8 | :class: sidebar 9 | 10 | The Diátaxis map is an effective reminder of the different kinds of 11 | documentation and their relationship, and it accords well with intuitions 12 | about documentation. 13 | 14 | However intuition is not always to be relied upon. Often when working with 15 | documentation, an author is faced with the question: *what form of 16 | documentation is this?* or *what form of documentation is needed here?* - and 17 | no obvious, intuitive answer. 18 | 19 | Worse, sometimes intuition provides an immediate answer that is also wrong. 20 | 21 | A map is most powerful in unfamiliar territory when we also have a compass to 22 | guide us. 23 | 24 | The Diátaxis compass is something like a truth-table or decision-tree of 25 | documentation. It reduces a more complex, two-dimensional problem to its 26 | simpler parts, and provides the author with a course-correction tool. 27 | 28 | 29 | .. list-table:: 30 | :widths: 33 33 34 31 | :header-rows: 1 32 | :stub-columns: 0 33 | :class: wider 34 | 35 | * - If the content... 36 | - ...and serves the user's... 37 | - ...then it must belong to... 38 | * - informs action 39 | - acquisition of skill 40 | - a tutorial 41 | * - informs action 42 | - application of skill 43 | - a how-to guide 44 | * - informs cognition 45 | - application of skill 46 | - reference 47 | * - informs cognition 48 | - acquisition of skill 49 | - explanation 50 | 51 | The compass can be applied equally to user situations that need documentation, or to documentation itself that perhaps needs to be moved or improved. Like many good tools, it's surprisingly banal. 52 | 53 | To use the compass, just two questions need to be asked: *action or cognition?* *acquisition or application?* 54 | 55 | And it yields the answer. 56 | 57 | 58 | Using the compass 59 | ------------------ 60 | 61 | The compass is particularly effective when you think that you think you (or even the documentation in front of you) are doing one thing - but you are troubled by a sense of doubt, or by some difficulty in the work. The compass forces you to stop and reconsider. 62 | 63 | Especially when you are trying to find your initial bearings, use the compass's terms flexibly; don't get fixated on the exact names. 64 | 65 | * *action*: practical steps, doing 66 | * *cognition*: theoretical or propositional knowledge, thinking 67 | * *acquisition*: study 68 | * *application*: work 69 | 70 | And the questions themselves can also be used in different ways: 71 | 72 | * Do I think I am writing for *x* or *y*? 73 | * Is this writing in front of me engaged in *x* or *y*? 74 | * Does the user need *x* or *y*? 75 | * Do I want to *x* or *y*? 76 | 77 | And try applying them close-up, at the level of sentences and words, or from a wider perspective, considering an entire document. 78 | -------------------------------------------------------------------------------- /complex-hierarchies.rst: -------------------------------------------------------------------------------- 1 | .. _complex-documentation: 2 | 3 | Diátaxis in complex hierarchies 4 | ================================== 5 | 6 | .. _basic-structure: 7 | 8 | Structure of documentation content 9 | ---------------------------------- 10 | 11 | The application of Diátaxis to most documentation is fairly straightforward. 12 | The product that defines the domain of concern has clear boundaries, and it's 13 | possible to come up with an arrangement of documentation contents that looks - for example - like this: 14 | 15 | .. code-block:: text 16 | 17 | Home <- landing page 18 | Tutorial <- landing page 19 | Part 1 20 | Part 2 21 | Part 3 22 | How-to guides <- landing page 23 | Install 24 | Deploy 25 | Scale 26 | Reference <- landing page 27 | Command-line tool 28 | Available endpoints 29 | API 30 | Explanation <- landing page 31 | Best practice recommendations 32 | Security overview 33 | Performance 34 | 35 | In each case, a landing page contains an overview of the contents within. The 36 | tutorial for example describes what the tutorial has to offer, providing 37 | context for it. 38 | 39 | Adding a layer of hierarchy 40 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ 41 | 42 | Even very large documentation sets can use this effectively, though after a 43 | while some grouping of content within sections might be wise. This can be done 44 | by adding another layer of hierarchy - for example to be able to address 45 | different installation options separately: 46 | 47 | .. code-block:: text 48 | :emphasize-lines: 7-11 49 | 50 | Home <- landing page 51 | Tutorial <- landing page 52 | Part 1 53 | Part 2 54 | Part 3 55 | How-to guides <- landing page 56 | Install <- landing page 57 | Local installation 58 | Docker 59 | Virtual machine 60 | Linux container 61 | Deploy 62 | Scale 63 | Reference <- landing page 64 | Command-line tool 65 | Available endpoints 66 | API 67 | Explanation <- landing page 68 | Best practice recommendations 69 | Security overview 70 | Performance 71 | 72 | 73 | Contents pages 74 | -------------- 75 | 76 | Contents pages - typically a home page and any landing pages - provide an overview of the material they encompass. 77 | 78 | There is an art to creating a good contents page. The experience they give the users deserves careful consideration. 79 | 80 | 81 | The problem of lists 82 | ~~~~~~~~~~~~~~~~~~~~ 83 | 84 | Lists longer than a few items are very hard for humans to read, unless they 85 | have an inherent mechanical order - numerical, or alphabetical. *Seven items 86 | seems to be a comfortable general limit.* If you find that you're looking at 87 | lists longer than that in your tables of contents, you probably need to find a way to 88 | break them up into small ones. 89 | 90 | As always, what matters most is **the experience of the reader**. Diátaxis works 91 | because it fits user needs well - if your execution of Diátaxis leads you to 92 | formats that seem uncomfortable or ugly, then you need to use it 93 | differently. 94 | 95 | Overviews and introductory text 96 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 97 | 98 | **The content of a landing page itself should read like an overview.** 99 | 100 | That is, it should not simply present lists of other content, it should 101 | introduce them. *Remember that you are always authoring for a human user, not 102 | fulfilling the demands of a scheme.* 103 | 104 | Headings and snippets of introductory text catch the eye and provide context; 105 | for example, a **how-to landing page**: 106 | 107 | .. code-block:: text 108 | 109 | How to guides 110 | ============= 111 | 112 | Lorem ipsum dolor sit amet, consectetur adipiscing elit. 113 | 114 | Installation guides 115 | ------------------- 116 | 117 | Pellentesque malesuada, ipsum ac mollis pellentesque, risus 118 | nunc ornare odio, et imperdiet dui mi et dui. Phasellus vel 119 | porta turpis. In feugiat ultricies ipsum. 120 | 121 | * Local installation | 122 | * Docker | links to 123 | * Virtual machines | the guides 124 | * Linux containers | 125 | 126 | Deployment and scaling 127 | ----------------------- 128 | 129 | Morbi sed scelerisque ligula. In dictum lacus quis felis 130 | facilisisvulputate. Quisque lacinia condimentum ipsum 131 | laoreet tempus. 132 | 133 | * Deploy an instance | links to 134 | * Scale your application | the guides 135 | 136 | 137 | Two-dimensional problems 138 | ------------------------ 139 | 140 | A more difficult problem is when the structure outlined by Diátaxis meets 141 | another structure - often, a structure of topic areas within the 142 | documentation, or when documentation encounters very different user-types. 143 | 144 | For example we might have a product that is used on land, sea and air, and 145 | though the same product, is used quite differently in each case. And it could 146 | be that a user who uses it on land is very unlikely to use it at sea. 147 | 148 | Or, the product documentation addresses the needs of: 149 | 150 | * users 151 | * developers who build other products around it 152 | * the contributors who help maintain it. 153 | 154 | The same product, but very different concerns. 155 | 156 | A final example: a product that can be deployed on different public clouds, 157 | with each public cloud presenting quite different workflows, commands, APIs, 158 | GUIs, constraints and so on. Even though it's the same product, as far as the 159 | users in each case are concerned, what they need to know and do is very 160 | different - what they need is documentation not for *product*, 161 | but 162 | 163 | * *product-on-public-cloud-one* 164 | * *product-on-public-cloud-two* 165 | * and so on... 166 | 167 | So, we *could* decide on an overall structure that does this: 168 | 169 | .. code-block:: text 170 | 171 | tutorial 172 | for users on land 173 | [...] 174 | for users at sea 175 | [...] 176 | for users in the air 177 | [...] 178 | [and then so on for how-to guides, reference and explanation] 179 | 180 | or maybe instead this: 181 | 182 | .. code-block:: text 183 | 184 | for users on land 185 | tutorial 186 | [...] 187 | how-to guides 188 | [...] 189 | reference 190 | [...] 191 | explanation 192 | [...] 193 | for users at sea 194 | [tutorial, how-to, reference, explanation sections] 195 | for users in the air 196 | [tutorial, how-to, reference, explanation sections] 197 | 198 | Which is better? There seems to be a lot of repetition in either cases. What 199 | about the material that can be shared between land, sea and air? 200 | 201 | 202 | What *is* the problem? 203 | ~~~~~~~~~~~~~~~~~~~~~~ 204 | 205 | Firstly, the problem is in no way limited to Diátaxis - there would be the 206 | difficulty of managing documentation in any case. However, Diátaxis certainly 207 | helps reveal the problem, as it does in many cases. It brings it into focus 208 | and demands that it be addressed. 209 | 210 | Secondly, the question highlights a common misunderstanding. Diátaxis is not a 211 | scheme into which documentation must be placed - four boxes. It posits four 212 | different kinds of documentation, around which documentation should be 213 | structured, but this does not mean that there must be simply four divisions 214 | of documentation in the hierarchy, one for each of those categories. 215 | 216 | 217 | Diátaxis as an approach 218 | ------------------------------------------ 219 | 220 | Diátaxis can be neatly represented in a diagram - but it is not 221 | the *same* as that diagram. 222 | 223 | It should be understood as an approach, a way of working with documentation, 224 | that identifies four different needs and uses them to author and structure 225 | documentation effectively. 226 | 227 | This will *tend* towards a clear, explicit, structural division into the four 228 | categories - but that is a typical outcome of the good practice, not its 229 | end. 230 | 231 | 232 | User-first thinking 233 | ------------------------------------------ 234 | 235 | **Diátaxis is underpinned by attention to user needs**, and once again it's that 236 | concern that must direct us. 237 | 238 | What we must document is the product *as it is for the user*, the product as 239 | it is in their hands and minds. (Sadly for the creators of products, how they 240 | conceive them is much less relevant.) 241 | 242 | Is the product on land, sea and air effectively three different products, 243 | perhaps for three different users? 244 | 245 | In that case, let that be the starting point for thinking about it. 246 | 247 | If the documentation needs to meet the needs of users, developers and 248 | contributors, how do *they* see the product? Should we assume that a 249 | developer who incorporates it into other products will typically need a good 250 | understanding of how it's used, and that a contributor needs to know what 251 | a developer knows too? 252 | 253 | Then perhaps it makes sense to be freer with the structure, in some parts 254 | (say, the tutorial) allowing the developer-facing content to follow on from 255 | the user-facing material, while completely separating the contributors' how-to 256 | guides from both. 257 | 258 | And so on. If the structure is not :ref:`the simple, uncomplicated structure we 259 | began with `, that's not a problem - as long as there *is* 260 | arrangement according to Diátaxis principles, that documentation does not 261 | muddle up its different forms and purposes. 262 | 263 | 264 | Let documentation be complex if necessary 265 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 266 | 267 | Documentation should be as complex as it needs to be. It will sometimes 268 | have complex structures. 269 | 270 | But, even complex structures can be made 271 | straightforward to navigate as long as they are logical and incorporate 272 | patterns that fit the needs of users. 273 | -------------------------------------------------------------------------------- /conf.py: -------------------------------------------------------------------------------- 1 | # Configuration file for the Sphinx documentation builder. 2 | # 3 | # This file only contains a selection of the most common options. For a full 4 | # list see the documentation: 5 | # http://www.sphinx-doc.org/en/master/config 6 | 7 | # -- Path setup -------------------------------------------------------------- 8 | 9 | # If extensions (or modules to document with autodoc) are in another directory, 10 | # add these directories to sys.path here. If the directory is relative to the 11 | # documentation root, use os.path.abspath to make it absolute, like shown here. 12 | # 13 | # import os 14 | # import sys 15 | # sys.path.insert(0, os.path.abspath('.')) 16 | 17 | 18 | # -- Project information ----------------------------------------------------- 19 | 20 | html_title = full_title = project = "Diátaxis" 21 | copyright = "Daniele Procida" 22 | author = "Daniele Procida" 23 | 24 | 25 | # -- General configuration --------------------------------------------------- 26 | 27 | # Add any Sphinx extension module names here, as strings. They can be 28 | # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom 29 | # ones. 30 | extensions = ["sphinx_design", "sphinx_reredirects"] 31 | 32 | # Add any paths that contain templates here, relative to this directory. 33 | templates_path = ["_templates"] 34 | 35 | # List of patterns, relative to source directory, that match files and 36 | # directories to ignore when looking for source files. 37 | # This pattern also affects html_static_path and html_extra_path. 38 | exclude_patterns = [ 39 | "_build", 40 | "Thumbs.db", 41 | ".DS_Store", 42 | "env", 43 | "LICENSE.rst", 44 | "README.rst", 45 | "stashed", 46 | ] 47 | 48 | # -- Options for HTML output ------------------------------------------------- 49 | 50 | # The theme to use for HTML and HTML Help pages. See the documentation for 51 | # a list of builtin themes. 52 | # 53 | html_theme = "furo" 54 | html_theme_options = { 55 | "sidebar_hide_name": True, 56 | "light_css_variables": { 57 | "color-background-secondary": "#fff", 58 | "color-sidebar-background-border": "none", 59 | }, 60 | "dark_css_variables": { 61 | "color-background-secondary": "#000", 62 | }, 63 | } 64 | html_static_path = ["_static"] 65 | html_logo = "images/diataxis-white-416.png" 66 | html_css_files = [ 67 | "diataxis.css", 68 | ] 69 | html_sidebars = { 70 | "**": [ 71 | "sidebar/scroll-start.html", 72 | "sidebar/brand.html", 73 | "sidebar/navigation.html", 74 | "sidebar/search.html", 75 | "sidebar/ethical-ads.html", 76 | "sidebar/scroll-end.html", 77 | ] 78 | } 79 | 80 | html_permalinks_icon = "¶" 81 | 82 | html_show_sphinx = False 83 | 84 | # Add any paths that contain custom static files (such as style sheets) here, 85 | # relative to this directory. They are copied after the builtin static files, 86 | # so a file named "default.css" will overwrite the builtin "default.css". 87 | 88 | master_doc = "index" 89 | 90 | html_favicon = "favicon.png" 91 | 92 | spelling_lang = tokenizer_lang = "en_GB" 93 | 94 | redirects = { 95 | "citation": "/colophon", 96 | "contact": "/colophon", 97 | "colofon": "/colophon", 98 | } 99 | -------------------------------------------------------------------------------- /diataxis.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/evildmp/diataxis-documentation-framework/c8921879b518087da556d2dec247adf48e3fab91/diataxis.png -------------------------------------------------------------------------------- /explanation.rst: -------------------------------------------------------------------------------- 1 | .. _explanation: 2 | 3 | Explanation 4 | =========== 5 | 6 | .. rubric:: Explanation is a discursive treatment of a subject, that permits *reflection*. Explanation is 7 | **understanding-oriented**. 8 | 9 | =========== 10 | 11 | Explanation deepens and broadens the reader's understanding of a subject. It brings clarity, light and context. 12 | 13 | .. image:: /images/overview-explanation.png 14 | :alt: Explanation - understanding oriented, theoretical knowledge, that serves our study 15 | :class: sidebar 16 | 17 | The concept of *reflection* is important. Reflection occurs *after* something else, and depends on something else, yet at the same time brings something new - shines a new light - on the subject matter. 18 | 19 | The perspective of explanation is higher and wider than that of the other three types. It does not take the user's eye-level view, as in a how-to guide, or a close-up view of the machinery, like reference material. Its scope in each case is a topic - "an area of knowledge", that somehow has to be bounded in a reasonable, meaningful way. 20 | 21 | For the user, explanation joins things together. It's an answer to the question: *Can you tell me about ...?* 22 | 23 | It's documentation that it makes sense to read while away from the product itself (one could say, explanation is the only kind of documentation that it might make sense to read in the bath). 24 | 25 | =========== 26 | 27 | The value and place of explanation 28 | ---------------------------------- 29 | 30 | Explanation and understanding 31 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 32 | 33 | Explanation is characterised by its distance from the active concerns of the practitioner. It doesn't have direct implications for what they do, or for their work. This means that it's sometimes seen as being of lesser importance. That's a mistake; it may be less *urgent* than the other three, but it's no less *important*. It's not a luxury. No practitioner of a craft can afford to be without an 34 | understanding of that craft, and needs the explanatory material that will help weave it together. 35 | 36 | .. sidebar:: Explanation by any other name 37 | 38 | Your explanation documentation doesn't need to be called *Explanation*. Alternatives include: 39 | 40 | * *Discussion* 41 | * *Background* 42 | * *Conceptual guides* 43 | * *Topics* 44 | 45 | The word *explanation* - and its cognates in other languages - refer to *unfolding*, the revelation of what is hidden in the folds. So explanation brings to the light things that were implicit or obscured. 46 | 47 | Similarly, words that mean *understanding* share roots in words meaning to hold or grasp (as in *comprehend*). That's an important part of understanding, to be able to hold something or be in possession of it. Understanding seals together the other components of our mastery of a craft, and makes it safely our own. 48 | 49 | Understanding doesn't *come from* explanation, but explanation is required to form that web that helps hold 50 | everything together. Without it, the practitioner's knowledge of their craft is loose and fragmented and fragile, and 51 | their exercise of it is *anxious*. 52 | 53 | 54 | Explanation and its boundaries 55 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 56 | 57 | Quite often explanation is not explicitly recognised in documentation; and the idea that things need to be 58 | explained is often only faintly expressed. Instead, explanation tends to be scattered in small parcels in other 59 | sections. 60 | 61 | It's not always easy to write good explanatory material. Where does one start? It's also not clear where to conclude. 62 | There is an open-endedness about it that can give the writer too many possibilities. 63 | 64 | Tutorials, how-to-guides and reference are all clearly defined in their scope by something that is also well-defined: 65 | by what you need the user to learn, what task the user needs to achieve, or just by the scope of the machine itself. 66 | 67 | In the case of explanation, it's useful to have a real or imagined *why* question to serve as a prompt. Otherwise, you 68 | simply have to draw some lines that mark out a reasonable area and be satisfied with that. 69 | 70 | 71 | 72 | ============== 73 | 74 | Writing good explanation 75 | ----------------------------------- 76 | 77 | Make connections 78 | ~~~~~~~~~~~~~~~~ 79 | 80 | When writing explanation you are helping to weave a web of understanding for your readers. **Make connections** to 81 | other things, even to things outside the immediate topic, if that helps. 82 | 83 | 84 | Provide context 85 | ~~~~~~~~~~~~~~~ 86 | 87 | **Provide background and context in your explanation**: explain *why* things are so - design decisions, historical 88 | reasons, technical constraints - draw implications, mention specific examples. 89 | 90 | 91 | Talk *about* the subject 92 | ~~~~~~~~~~~~~~~~~~~~~~~~ 93 | 94 | .. sidebar:: Things to discuss 95 | 96 | * the bigger picture 97 | * history 98 | * choices, alternatives, possibilities 99 | * why: reasons and justifications 100 | 101 | Explanation guides are *about* a topic in the sense that they are *around* it. Even the names of your explanation 102 | guides should reflect this; you should be able to place an implicit (or even explicit) *about* in front of each 103 | title. For example: *About user authentication*, or *About database connection policies*. 104 | 105 | 106 | Admit opinion and perspective 107 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 108 | 109 | Opinion might seem like a funny thing to introduce into documentation. The fact is that all human activity and knowledge is invested within opinion, with beliefs and thoughts. The reality of any human creation is rich with opinion, and that needs to be part of any understanding of it. 110 | 111 | Similarly, any understanding comes from a perspective, a particular stand-point - which means that other perspectives and stand-points exist. **Explanation can and must consider alternatives**, counter-examples or multiple different approaches to the same question. 112 | 113 | In explanation, you're not giving instruction or describing facts - you're opening up the topic for consideration. It helps to think of explanation as discussion: discussions can even consider and weigh up contrary *opinions*. 114 | 115 | 116 | Keep explanation closely bounded 117 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 118 | 119 | One risk of explanation is that it tends to absorb other things. The writer, intent on covering the topic, feels the urge to include instruction or technical description related to it. But documentation already has other places for these, and allowing them to creep in interferes with the explanation itself, and removes them from view in the correct place. 120 | 121 | 122 | ============== 123 | 124 | The language of explanation 125 | -------------------------------- 126 | 127 | *The reason for x is because historically, y ...* 128 | Explain. 129 | *W is better than z, because ...* 130 | Offer judgements and even opinions where appropriate.. 131 | *An x in system y is analogous to a w in system z. However ...* 132 | Provide context that helps the reader. 133 | *Some users prefer w (because z). This can be a good approach, but...* 134 | Weigh up alternatives. 135 | *An x interacts with a y as follows: ...* 136 | Unfold the machinery's internal secrets, to help understand why something does what it does. 137 | 138 | ================ 139 | 140 | Analogy from food and cooking 141 | ----------------------------- 142 | 143 | 144 | In 1984 `Harold McGee `_ published *On food and cooking*. 145 | 146 | .. image:: /images/mcgee.jpg 147 | :alt: 148 | :class: floated 149 | 150 | The book doesn't teach how to cook anything. It doesn't contain recipes (except as historical examples) and it isn't a work of reference. Instead, it places food and cooking in the context of history, society, science and technology. It explains for example why we do what we do in the kitchen and how that has changed. 151 | 152 | It's clearly not a book we would read *while* cooking. We would read when we want to reflect on cooking. It illuminates the subject by taking multiple different perspectives on it, shining light from different angles. 153 | 154 | After reading a book like *On food and cooking*, our understanding is changed. Our knowledge is richer and deeper. What we have learned may or may not be immediately applicable next time we are doing something in the kitchen, but *it will change how 155 | we think about our craft, and will affect our practice*. 156 | -------------------------------------------------------------------------------- /favicon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/evildmp/diataxis-documentation-framework/c8921879b518087da556d2dec247adf48e3fab91/favicon.png -------------------------------------------------------------------------------- /foundations.rst: -------------------------------------------------------------------------------- 1 | Foundations 2 | =========== 3 | 4 | Diátaxis is successful because it *works* - both users and creators have a better experience of documentation as a result. It makes sense and it feels right. 5 | 6 | However, that's not enough to be confident in Diátaxis as a theory of documentation. As a theory, it needs to show *why* it works. It needs to show that there is actually some reason why there are exactly four kinds of documentation, not three or five. It needs to demonstrate rigorous thinking and analysis, and that it stands on a sound theoretical foundation. 7 | 8 | Otherwise, it will be just another useful heuristic approach, and the strongest claim we can make for it is that "it seems to work quite well". 9 | 10 | 11 | Two dimensions of craft 12 | ----------------------- 13 | 14 | Diátaxis is based on the principle that documentation must serve the needs of its users. Knowing how to do that means understanding what the needs of users are. 15 | 16 | The user whose needs Diátaxis serves is *the practitioner in a domain of skill*. A domain of skill is defined by a craft - the use of a tool or product is a craft. So is an entire discipline or profession. Using a programming language is a craft, as is flying a particular aircraft, or even being a pilot in general. 17 | 18 | Understanding the needs of these users means in turn understanding the essential characteristics of craft or skill. 19 | 20 | 21 | Action/cognition 22 | ~~~~~~~~~~~~~~~~ 23 | 24 | A skill or craft or practice contains both **action** (practical knowledge, knowing *how*, what we do) and **cognition** (theoretical knowledge, knowing *that*, what we think). The two are completely bound up with each other, but they are counterparts, wholly distinct from each, two different aspects of the same thing. 25 | 26 | 27 | Acquisition/application 28 | ~~~~~~~~~~~~~~~~~~~~~~~ 29 | 30 | Similarly, the relationship of a practitioner with their practice is that it is something that needs to be both **acquired**, and **applied**. Being "at work" (concerned with applying the skill and knowledge of their craft) and being "at study" (concerned with acquiring them) are once again counterparts, distinct but bound up with each other. 31 | 32 | 33 | The map of the territory 34 | ~~~~~~~~~~~~~~~~~~~~~~~~ 35 | 36 | This gives us two dimensions of skill, that we can lay out on a map - a map of the territory of craft: 37 | 38 | .. image:: /images/two-dimensions.png 39 | :alt: The territory of craft as a two-dimensional map 40 | 41 | This is a *complete* map. There are only two dimensions, and they don't just cover the entire territory, they define it. This is why there are necessarily four quarters to it, and there could not be three, or five. It is not an arbitrary number. 42 | 43 | It also shows us the *qualities* of craft that define each of them. When the idea that documentation must serve the needs of craft is applied to this map, it reveals in turn what documentation must be and do to fulfil those obligations - in four distinct ways. 44 | 45 | 46 | Serving needs 47 | ------------- 48 | 49 | The map of the territory of craft is what gives us the familiar Diátaxis map of documentation. The map is in effect an answer to the question: what must documentation do to align with these qualities of skill, and to what need is it oriented in each case? 50 | 51 | .. image:: /images/axes-of-needs.png 52 | :alt: The territory of craft as a two-dimensional map 53 | 54 | We can see how the map of documentation addresses *needs* across those two dimensions, each need also defined by the characteristics of its quarter of the map. 55 | 56 | 57 | .. list-table:: 58 | :header-rows: 1 59 | :widths: 22 22 26 30 60 | 61 | * - need 62 | - addressed in 63 | - the user 64 | - the documentation 65 | * - learning 66 | - tutorials 67 | - acquires their craft 68 | - informs action 69 | * - goals 70 | - how-to guides 71 | - applies their craft 72 | - informs action 73 | * - information 74 | - reference 75 | - applies their craft 76 | - informs cognition 77 | * - understanding 78 | - explanation 79 | - acquires their craft 80 | - informs cognition 81 | 82 | 83 | The Diátaxis map of documentation is a memorable and approachable idea. But, a map is only reliable if it adequately describes a reality. Diátaxis is underpinned by a systematic description and analysis of generalised **user needs**. 84 | 85 | This is why the tutorials, how-to guides, reference and explanation of Diátaxis are a complete enumeration of the types of documentation that serve practitioners in a craft. This is why there are four and only four types of documentation. There is simply no other territory to cover. 86 | 87 | -------------------------------------------------------------------------------- /how-to-guides.rst: -------------------------------------------------------------------------------- 1 | .. _how-to: 2 | 3 | How-to guides 4 | ============= 5 | 6 | .. rubric:: How-to guides are **directions** that guide the reader through a problem or towards a result. How-to guides are **goal-oriented**. 7 | 8 | =========== 9 | 10 | A how-to guide helps the user get something done, correctly and safely; it guides the user's *action*. 11 | 12 | It's concerned with *work* - navigating from one side to the other of a real-world problem-field. 13 | 14 | .. image:: /images/overview-how-to.png 15 | :alt: How-to guides - task oriented, practical steps, that serve our work 16 | :class: sidebar 17 | 18 | Examples could be: *how to calibrate the radar array*; *how to use fixtures in pytest*; *how to configure 19 | reconnection back-off policies*. On the other hand, *how to build a web application* is not - that's not 20 | addressing a specific goal or problem, it's a vastly open-ended sphere of skill. 21 | 22 | How-to guides matter not just because users need to be able to accomplish things: the list of how-to guides in your 23 | documentation helps frame the picture of what your product can actually *do*. A rich list of how-to guides is an 24 | encouraging suggestion of a product's capabilities. 25 | 26 | Well-written how-to guides that address the right questions are likely to be the most-read sections of your documentation. 27 | 28 | ================= 29 | 30 | How-to guides addressed to problems 31 | ----------------------------------- 32 | 33 | **How-to guides must be written from the perspective of the user, not of the machinery.** A how-to guide represents something that someone needs to get done. It's defined in other words by the needs of a user. Every how-to guide should answer to a human project, in other words. It should show what the human needs to do, with the tools at hand, to obtain the result they need. 34 | 35 | This is in strong contrast to common pattern for how-to guides that often prevails, in which how-to guides are defined by operations that can be performed with a tool or system. The problem with this latter pattern is that it offers little value to the user; it is not addressed to any need the user has. Instead, it's focused on the tool, on taking the machinery through its motions. 36 | 37 | This is fundamentally a distinction of *meaningfulness*. Meaning is given by purpose and need. There is no purpose or need in the functionality of a machine. It is merely a series of causes and effects, inputs and outputs. 38 | 39 | Consider: 40 | 41 | * "To shut off the flow of water, turn the tap clockwise." 42 | * "To deploy the desired database configuration, select the appropriate options and press **Deploy**." 43 | 44 | .. sidebar:: 45 | 46 | We really do not need to be informed that we turn on a device using the power switch, but it is shocking how often how-to guides in software documentation are written at this level. 47 | 48 | The examples above *look* like examples of guidance, but they are not. 49 | 50 | They represent mostly useless information that anyone with basic competence - anyone who is working in this domain - should be expected to know. Between them, standardised interfaces and generally-expected knowledge should make it quite clear what effect most actions will have. 51 | 52 | Secondly, they are disconnected from purpose. What the user needs to know might be things like: 53 | 54 | * how much water to run, and how vigorously to run it, for a certain purpose 55 | * what database configuration options align with particular real-world needs 56 | 57 | .. sidebar:: 58 | 59 | How-to guides are about goals, projects and problems, not about tools. 60 | 61 | Tools appear in how-to guides as incidental bit-players, the means to the user's end. Sometimes of course, a particular end is closely aligned with a particular tool or part of the system, and then you will find that a how-to guide indeed concentrates on that. Just as often, a how-to guide will cut across different tools or parts of a system, joining them up together in a series of activities defined by something a human being needs to get done. In either case, it is that project that defines what a how-to guide must cover. 62 | 63 | 64 | ================= 65 | 66 | What how-to guides are not 67 | -------------------------- 68 | 69 | **How-to guides are wholly distinct from tutorials**. They are often confused, but the user needs that they serve are quite different. Conflating them is at the root of many difficulties that afflict documentation. See :ref:`tutorials-how-to` for a discussion of this distinction. 70 | 71 | In another confusion, how-to guides are often construed merely as procedural guides. But solving a problem or accomplishing a task cannot always be reduced to a procedure. Real-world problems do not always offer themselves up to linear solutions. The sequences of action in a how-to guide sometimes need to fork and overlap, and they have multiple entry and exit-points. Often, a how-to guide will need the user to rely on their judgement in applying the guidance it can provide. 72 | 73 | 74 | ================= 75 | 76 | Key principles 77 | --------------------------------------- 78 | 79 | A how to-guide is concerned with work - a task or problem, with a practical goal. *Maintain focus on that goal*. 80 | 81 | .. sidebar:: How-to characteristics 82 | 83 | * focused on tasks or problems 84 | * assume the user knows what they want to achieve 85 | * action and only action 86 | * no digression, explanation, teaching 87 | 88 | Anything else that's added distracts both you and the user and dilutes the useful power of the guide. Typically, the temptations are to explain or to provide reference for completeness. Neither of these are part of guiding the user in their work. They get in the way of the action; if they're important, link to them. 89 | 90 | A how-to guide serves the work of the already-competent user, whom you can assume to know what they want to do, and to be able to follow your instructions correctly. 91 | 92 | 93 | Address real-world complexity 94 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 95 | 96 | **A how-to guide needs to be adaptable to real-world use-cases**. One that is useless for any purpose except *exactly* the narrow one you have addressed is rarely valuable. You can't address every possible case, so you must find ways to remain open to the range of possibilities, in such a way that the user can adapt your guidance to their needs. 97 | 98 | Omit the unnecessary 99 | ~~~~~~~~~~~~~~~~~~~~ 100 | 101 | In how-to guides, **practical usability is more helpful than completeness.** Whereas a tutorial needs to be a complete, 102 | end-to-end guide, a how-to guide does not. It should start and end in some reasonable, meaningful place, and require 103 | the reader to join it up to their own work. 104 | 105 | 106 | Provide a set of instructions 107 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 108 | 109 | A how-to guide describes an *executable solution* to a real-world problem or task. It's in the form of a contract: if you're facing this situation, then you can work your way through it by taking the steps outlined in this approach. The steps are in the form of *actions*. 110 | 111 | "Actions" in this context includes physical acts, but also thinking and judgement - solving a problem involves thinking it through. A how-to guide should address how the user thinks as well as what the user does. 112 | 113 | 114 | Describe a logical sequence 115 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ 116 | 117 | The fundamental structure of a how-to guide is a *sequence*. It implies logical ordering in time, that there is a sense and meaning to this particular order. 118 | 119 | In many cases, the ordering is simply imposed by the way things must be (step two requires completion of step one, for example). In this case it's obvious what order your directions should take. 120 | 121 | Sometimes the need is more subtle - it might be possible to *perform* two operations in either order, but if for example one operation helps set up the user's working environment or even their thinking in a way that benefits the other, that's a good reason for putting it first. 122 | 123 | 124 | Seek flow 125 | ~~~~~~~~~ 126 | 127 | At all times, try to ground your sequences in the patterns of the *user's* activities and thinking, in such a way that the guide acquires *flow*: smooth progress. 128 | 129 | Achieving flow means successfully understanding the user. Paying attention to sense and meaning in ordering requires paying attention to the way human beings think and act, and the needs of someone following directions. 130 | 131 | Again, this can be somewhat obvious: a workflow that has the user repeatedly switching between contexts and tools is clearly clumsy and inefficient. But you should look more deeply than this. What are you asking the user to think about, and how will their thinking flow from subject to subject during their work? How long do you require the user to hold thoughts open before they can be resolved in action? If you require the user to jump back to earlier concerns, is this necessary or avoidable? 132 | 133 | A how-to guide is concerned not just with logical ordering in time, but action taking place in time. Action, and a guide to it, has pace and rhythm. Badly-judged pace or disrupted rhythm are both damaging to flow. 134 | 135 | At its best, how-to documentation gives the user flow. There is a distinct experience of encountering a guide that appears to *anticipate* the user - the documentation equivalent of a helper who has the tool you were about to reach for, ready to place it in your hand. 136 | 137 | 138 | Pay attention to naming 139 | ~~~~~~~~~~~~~~~~~~~~~~~~ 140 | 141 | **Choose titles that say exactly what a how-to guide shows.** 142 | 143 | * good: *How to integrate application performance monitoring* 144 | * bad: *Integrating application performance monitoring* (maybe the document is about how to decide whether you should, not about how to do it) 145 | * very bad: *Application performance monitoring* (maybe it's about *how* - but maybe it's about *whether*, or even just an explanation of *what* it is) 146 | 147 | Note that search engines appreciate good titles just as much as humans do. 148 | 149 | ============== 150 | 151 | The language of how-to guides 152 | ----------------------------- 153 | 154 | *This guide shows you how to...* 155 | Describe clearly the problem or task that the guide shows the user how to solve. 156 | *If you want x, do y. To achieve w, do z.* 157 | Use conditional imperatives. 158 | *Refer to the x reference guide for a full list of options.* 159 | Don't pollute your practical how-to guide with every possible thing the user might do related to x. 160 | 161 | 162 | ================ 163 | 164 | Applied to food and cooking 165 | --------------------------- 166 | 167 | Consider a recipe, an excellent model for a how-to guide. A recipe clearly defines what will be achieved by following it, and **addresses a specific question** (*How do I make...?* or *What can I make with...?*). 168 | 169 | .. image:: /images/old-recipe.jpg 170 | :alt: A recipe contains a list of ingredients and a list of steps. 171 | 172 | It's not the responsibility of a recipe to *teach* you how to make something. A professional chef who has made exactly the same thing multiple times before may still follow a recipe - even if they *created* the recipe themselves - to ensure that they do it correctly. 173 | 174 | Even following a recipe **requires at least basic competence**. Someone who has never cooked before should not be expected to follow a recipe with success, so a recipe is not a substitute for a cooking lesson. 175 | 176 | Someone who expected to be provided with a recipe, and is given instead a cooking lesson, will be disappointed and annoyed. Similarly, while it's interesting to read about the context or history of a particular dish, the one time you don't want to be faced with that is while you are in the middle of trying to make it. A good recipe follows a well-established format, that excludes both teaching and discussion, and focuses only on **how** to make the dish concerned. 177 | -------------------------------------------------------------------------------- /how-to-use-diataxis.rst: -------------------------------------------------------------------------------- 1 | .. _how-to-use-diataxis: 2 | 3 | Diátaxis as a guide to work 4 | =========================== 5 | 6 | As well as providing a guide to documentation content, Diátaxis is also a guide to documentation process and execution. 7 | 8 | Most people who work on technical documentation must make decisions about how to work, as they work. In some contexts, documentation must be delivered once, complete and in its final state, but it's more usual that it's an on-going project, for example developed alongside a product that itself evolves and develops. It's also the experience of many people who work on documentation to find themselves responsible for improving or even remediating a body of work. 9 | 10 | Diátaxis provides an approach to work that runs counter to much of the accepted wisdom in documentation. In particular, it discourages planning and top-down workflows, preferring instead small, responsive iterations from which overall patterns emerge. 11 | 12 | 13 | Use Diátaxis as a guide, not a plan 14 | ----------------------------------- 15 | 16 | Diátaxis describes a complete picture of documentation. However the structure it proposes is not intended to be a 17 | **plan**, something you must complete in your documentation. It's a **guide**, a map to help you check that you're in 18 | the right place and going in the right directions. 19 | 20 | The point of Diátaxis is to give you a way to think about and understand your documentation, so that you can make 21 | better sense of what it's doing and what you're trying to do with it. It provides tools that help assess it, identify 22 | where its problems lie, and judge what you can do to improve it. 23 | 24 | 25 | Don't worry about structure 26 | ----------------------------------------- 27 | 28 | Although structure is key to documentation, **using Diátaxis means not spending energy trying to get its structure 29 | correct**. 30 | 31 | If you continue to follow the prompts that Diátaxis provides, eventually your documentation will assume the 32 | Diátaxis structure - but it will have assumed that shape *because* it has been improved. It's not the other way round, 33 | that the structure must be imposed upon documentation to improve it. 34 | 35 | Getting started with Diátaxis does not require you to think about dividing up your documentation into four sections. **It certainly does not mean that you should create empty structures for tutorials/howto guides/reference/explanation with nothing in them.** Don't do that. It's horrible. 36 | 37 | Instead, following the workflow described in the next two sections, make changes where you see opportunities for 38 | improvement according to Diátaxis principles, so that the documentation starts to take a certain shape. At a certain 39 | point, the changes you have made will appear to demand that you move material under a certain Diátaxis heading - and 40 | that is how your top-level structure will form. In other words, **Diátaxis changes the structure of your documentation 41 | from the inside**. 42 | 43 | 44 | Work one step at a time 45 | --------------------------------------------- 46 | 47 | Diátaxis strongly prescribes a structure, but whatever the state of your existing documentation - even if it's a 48 | complete mess by any standards - it's always possible to improve it, **iteratively**. 49 | 50 | It's natural to want to complete large tranches of work before you publish them, so that you have something substantial 51 | to show each time. Avoid this temptation - every step in the right direction is worth publishing immediately. 52 | 53 | Although Diátaxis is intended to provide a big picture of documentation, **don't try to work on the big picture**. It's 54 | both unnecessary and unhelpful. Diátaxis is designed to guide small steps; keep taking small steps to arrive where you 55 | want to go. 56 | 57 | 58 | Just do something 59 | ------------------- 60 | 61 | If you're tidying up a huge mess, the temptation is to tear it all down and start again. Again, avoid it. As far as 62 | improving documentation in-line with Diátaxis goes, it isn't necessary to seek out things to improve. Instead, the best 63 | way to apply Diátaxis is as follows: 64 | 65 | **Choose something** - any piece of the documentation. If you don’t already have something that you know you want to 66 | put right, don't go looking for outstanding problems. Just look at what you have right in front of you at that moment: 67 | the file you’re in, the last page you read - it doesn’t matter. If there isn’t one just choose something, literally at 68 | random. 69 | 70 | **Assess it**. Next consider this thing critically. Preferably it’s a small thing, nothing bigger than a page - or 71 | better, even smaller, a paragraph or a sentence. Challenge it, according to the standards Diátaxis prescribes: *What 72 | user need is represented by this? How well does it serve that need? What can be added, moved, removed or changed to 73 | serve that need better? Do its language and logic meet the requirements of this mode of documentation?* 74 | 75 | **Decide what to do**. Decide, based on your answers to those questions: *What single next action will produce an 76 | immediate improvement here?* 77 | 78 | **Do it**. Complete that next single action, *and consider it completed* - i.e. publish it, or at least commit the 79 | change. Don't feel that you need to do anything else to make a worthy improvement. 80 | 81 | And then go back to the beginning of the cycle. 82 | 83 | Working like this helps reduce the stress of one of the most paralysing and troublesome aspects of the 84 | documentation-writer's work: working out what to do. It keeps work flowing in the right direction, always towards the 85 | desired end, without having to expend energies on a plan. 86 | 87 | 88 | Allow your work to develop organically 89 | ---------------------------------------- 90 | 91 | There's a strong urge to work in a cycle of planning and execution in order to work towards results. But it's not the 92 | only way, and there are often better ways when working with documentation. 93 | 94 | Well-formed organic growth 95 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ 96 | 97 | A good model for documentation is **well-formed organic growth that adapts to external conditions**. Organic growth 98 | takes place at the cellular level. The structure of the organism as a whole is guaranteed by the healthy development of 99 | cells, according to rules that are appropriate to each kind of cell. It's not the other way round, that a structure is 100 | imposed on the organism from above or outside. Good structure develops from within. 101 | 102 | .. figure:: /images/always-complete.jpg 103 | :figclass: wider 104 | :alt: 105 | 106 | Illustration copyright `Linette Voller `_ 2021, reproduced with kind permission. 107 | 108 | It's the same with documentation: by following the principles that Diátaxis provides, your documentation will 109 | attain a healthy structure, because its internal components themselves are well-formed - like a living organism, it 110 | will have built itself up from the inside-out, one cell at a time. 111 | 112 | Complete, not finished 113 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 114 | 115 | Consider a plant. As a living, growing organism, a plant is **never finished** - it can always develop further, move on 116 | to the next stage of growth and maturity. But, at every stage of its development, from seed to a fully-mature tree, 117 | it's **always complete** - there's never something missing from it. At any point, it is in a state that is appropriate 118 | to its stage of development. 119 | 120 | Similarly, documentation is also never finished, because it always has to keep adapting and changing to the product and 121 | to users' needs, and can always be developed and improved further. 122 | 123 | However it can always be complete: useful to users, appropriate to its current stage of development, and in a healthy 124 | structural state and ready to go on to the next stage. 125 | 126 | -------------------------------------------------------------------------------- /images/acquisition-application.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/evildmp/diataxis-documentation-framework/c8921879b518087da556d2dec247adf48e3fab91/images/acquisition-application.png -------------------------------------------------------------------------------- /images/action-cognition.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/evildmp/diataxis-documentation-framework/c8921879b518087da556d2dec247adf48e3fab91/images/action-cognition.png -------------------------------------------------------------------------------- /images/always-complete.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/evildmp/diataxis-documentation-framework/c8921879b518087da556d2dec247adf48e3fab91/images/always-complete.jpg -------------------------------------------------------------------------------- /images/anselmo.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/evildmp/diataxis-documentation-framework/c8921879b518087da556d2dec247adf48e3fab91/images/anselmo.jpg -------------------------------------------------------------------------------- /images/axes-of-needs.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/evildmp/diataxis-documentation-framework/c8921879b518087da556d2dec247adf48e3fab91/images/axes-of-needs.png -------------------------------------------------------------------------------- /images/bookshelves.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/evildmp/diataxis-documentation-framework/c8921879b518087da556d2dec247adf48e3fab91/images/bookshelves.jpg -------------------------------------------------------------------------------- /images/diataxis-white-416.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/evildmp/diataxis-documentation-framework/c8921879b518087da556d2dec247adf48e3fab91/images/diataxis-white-416.png -------------------------------------------------------------------------------- /images/diataxis-white-original.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/evildmp/diataxis-documentation-framework/c8921879b518087da556d2dec247adf48e3fab91/images/diataxis-white-original.png -------------------------------------------------------------------------------- /images/diataxis-white.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/evildmp/diataxis-documentation-framework/c8921879b518087da556d2dec247adf48e3fab91/images/diataxis-white.png -------------------------------------------------------------------------------- /images/diataxis.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/evildmp/diataxis-documentation-framework/c8921879b518087da556d2dec247adf48e3fab91/images/diataxis.png -------------------------------------------------------------------------------- /images/lasagne.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/evildmp/diataxis-documentation-framework/c8921879b518087da556d2dec247adf48e3fab91/images/lasagne.jpg -------------------------------------------------------------------------------- /images/map-movement.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/evildmp/diataxis-documentation-framework/c8921879b518087da556d2dec247adf48e3fab91/images/map-movement.png -------------------------------------------------------------------------------- /images/mcgee.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/evildmp/diataxis-documentation-framework/c8921879b518087da556d2dec247adf48e3fab91/images/mcgee.jpg -------------------------------------------------------------------------------- /images/old-recipe.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/evildmp/diataxis-documentation-framework/c8921879b518087da556d2dec247adf48e3fab91/images/old-recipe.jpg -------------------------------------------------------------------------------- /images/operation.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/evildmp/diataxis-documentation-framework/c8921879b518087da556d2dec247adf48e3fab91/images/operation.jpg -------------------------------------------------------------------------------- /images/overview-explanation.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/evildmp/diataxis-documentation-framework/c8921879b518087da556d2dec247adf48e3fab91/images/overview-explanation.png -------------------------------------------------------------------------------- /images/overview-how-to.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/evildmp/diataxis-documentation-framework/c8921879b518087da556d2dec247adf48e3fab91/images/overview-how-to.png -------------------------------------------------------------------------------- /images/overview-reference.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/evildmp/diataxis-documentation-framework/c8921879b518087da556d2dec247adf48e3fab91/images/overview-reference.png -------------------------------------------------------------------------------- /images/overview-tutorials.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/evildmp/diataxis-documentation-framework/c8921879b518087da556d2dec247adf48e3fab91/images/overview-tutorials.png -------------------------------------------------------------------------------- /images/partial-collapse.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/evildmp/diataxis-documentation-framework/c8921879b518087da556d2dec247adf48e3fab91/images/partial-collapse.png -------------------------------------------------------------------------------- /images/suture.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/evildmp/diataxis-documentation-framework/c8921879b518087da556d2dec247adf48e3fab91/images/suture.jpg -------------------------------------------------------------------------------- /images/total-collapse.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/evildmp/diataxis-documentation-framework/c8921879b518087da556d2dec247adf48e3fab91/images/total-collapse.png -------------------------------------------------------------------------------- /images/two-dimensions.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/evildmp/diataxis-documentation-framework/c8921879b518087da556d2dec247adf48e3fab91/images/two-dimensions.png -------------------------------------------------------------------------------- /images/wheat.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/evildmp/diataxis-documentation-framework/c8921879b518087da556d2dec247adf48e3fab91/images/wheat.jpg -------------------------------------------------------------------------------- /index.rst: -------------------------------------------------------------------------------- 1 | .. meta:: 2 | :description: 3 | Diátaxis is a widely-adopted, pragmatic and systematic approach to thinking about and creating documentation. 4 | :keywords: documentation, four, kinds, architecture 5 | 6 | .. _diataxis: 7 | 8 | Diátaxis 9 | ======================================================== 10 | 11 | .. toctree:: 12 | :maxdepth: 1 13 | :hidden: 14 | :titlesonly: 15 | 16 | Home 17 | 18 | .. rubric:: A systematic approach to technical documentation authoring. 19 | 20 | ---------- 21 | 22 | Diátaxis is a way of thinking about and doing documentation. 23 | 24 | It prescribes approaches to content, architecture and form that emerge from a systematic approach to understanding the needs of documentation users. 25 | 26 | 27 | Diátaxis identifies four distinct needs, and four corresponding forms of documentation - *tutorials*, *how-to guides*, *technical reference* and *explanation*. It places them in a systematic relationship, and proposes that documentation should itself be organised around the structures of those needs. 28 | 29 | .. image:: /images/diataxis.png 30 | :alt: Diátaxis 31 | :class: wider 32 | 33 | .. sidebar:: 34 | 35 | *Diátaxis*, from the Ancient Greek δῐᾰ́τᾰξῐς: *dia* ("across") and *taxis* ("arrangement"). 36 | 37 | Diátaxis solves problems related to documentation *content* (what to write), *style* (how to write it) and *architecture* (how to organise it). 38 | 39 | As well as serving the users of documentation, Diátaxis has value for documentation creators and maintainers. It is light-weight, easy to grasp and straightforward to apply. It doesn't impose implementation constraints. It brings an active principle of quality to documentation that helps maintainers think effectively about their own work. 40 | 41 | ------ 42 | 43 | Contents 44 | -------- 45 | 46 | 47 | .. grid:: 1 2 2 2 48 | :padding: 0 49 | :margin: 0 50 | :gutter: 3 51 | 52 | .. grid-item:: 53 | 54 | The best way to get started with Diátaxis is by applying it after reading a brief primer. 55 | 56 | .. grid-item:: 57 | 58 | .. rst-class:: toc-with-header 59 | 60 | .. toctree:: 61 | :maxdepth: 1 62 | :titlesonly: 63 | 64 | Start here 65 | 66 | .. grid-item:: 67 | 68 | These pages will help make immediate, concrete sense of the approach. 69 | 70 | .. grid-item:: 71 | 72 | .. rst-class:: toc-with-header 73 | 74 | .. toctree:: 75 | :maxdepth: 1 76 | :titlesonly: 77 | 78 | application 79 | Tutorials 80 | How-to guides 81 | Reference 82 | Explanation 83 | compass 84 | Workflow 85 | 86 | .. grid-item:: 87 | 88 | This section explores the theory and principles of Diátaxis more deeply, and sets forth the understanding of needs that underpin it. 89 | 90 | .. grid-item:: 91 | 92 | .. rst-class:: toc-with-header 93 | 94 | .. toctree:: 95 | :maxdepth: 1 96 | :titlesonly: 97 | 98 | theory 99 | foundations 100 | map 101 | Quality 102 | Tutorials and how-to guides 103 | Reference and explanation 104 | Complex hierarchies 105 | The body 106 | 107 | -------- 108 | 109 | Diátaxis is proven in practice. Its principles have been adopted successfully in hundreds of documentation projects. 110 | 111 | 112 | .. epigraph:: 113 | 114 | Diátaxis has allowed us to build a high-quality set of internal documentation that our users love, and our contributors love adding to. 115 | 116 | -- Greg Frileux, `Vonage `_ 117 | 118 | .. epigraph:: 119 | 120 | At Gatsby we recently reorganized our open-source documentation, and the Diátaxis framework was our go-to resource 121 | throughout the project. The four quadrants helped us prioritize the user’s goal for each type of documentation. By 122 | restructuring our documentation around the Diátaxis framework, we made it easier for users to discover the 123 | resources that they need when they need them. 124 | 125 | -- `Megan Sullivan `_ 126 | 127 | 128 | .. epigraph:: 129 | 130 | While redesigning the `Cloudflare developer docs `_, Diátaxis became our north star for information architecture. When we weren't sure where a new piece of content should fit in, we'd consult the framework. Our documentation is now clearer than it's ever been, both for readers and contributors. 131 | 132 | -- `Adam Schwartz `_ 133 | 134 | 135 | 136 | 137 | 138 | 139 | .. toctree:: 140 | :maxdepth: 1 141 | :hidden: 142 | :titlesonly: 143 | 144 | colophon 145 | -------------------------------------------------------------------------------- /make.bat: -------------------------------------------------------------------------------- 1 | @ECHO OFF 2 | 3 | pushd %~dp0 4 | 5 | REM Command file for Sphinx documentation 6 | 7 | if "%SPHINXBUILD%" == "" ( 8 | set SPHINXBUILD=sphinx-build 9 | ) 10 | set SOURCEDIR=. 11 | set BUILDDIR=_build 12 | 13 | if "%1" == "" goto help 14 | 15 | %SPHINXBUILD% >NUL 2>NUL 16 | if errorlevel 9009 ( 17 | echo. 18 | echo.The 'sphinx-build' command was not found. Make sure you have Sphinx 19 | echo.installed, then set the SPHINXBUILD environment variable to point 20 | echo.to the full path of the 'sphinx-build' executable. Alternatively you 21 | echo.may add the Sphinx directory to PATH. 22 | echo. 23 | echo.If you don't have Sphinx installed, grab it from 24 | echo.http://sphinx-doc.org/ 25 | exit /b 1 26 | ) 27 | 28 | %SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% 29 | goto end 30 | 31 | :help 32 | %SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% 33 | 34 | :end 35 | popd 36 | -------------------------------------------------------------------------------- /map.rst: -------------------------------------------------------------------------------- 1 | .. _map: 2 | 3 | The map 4 | ======= 5 | 6 | 7 | One reason Diátaxis is effective as a guide to organising documentation is 8 | that it describes a **two-dimensional structure**, rather than a *list*. 9 | 10 | .. image:: /images/diataxis.png 11 | :alt: 12 | :class: sidebar 13 | 14 | It specifies its types of documentation in such a way that the structure 15 | naturally helps guide and shape the material it contains. 16 | 17 | As a map, it places the different forms of documentation into relationships 18 | with each other. Each one occupies a space in the mental territory it outlines, 19 | and the boundaries between them highlight their distinctions. 20 | 21 | 22 | The problem of structure 23 | ------------------------ 24 | 25 | When documentation fails to attain a good structure, it's rarely just a problem of structure (though it's bad enough that it makes it harder to use and maintain). Architectural faults infect and undermine content too. 26 | 27 | In the absence of a clear, generalised documentation architecture, documentation creators will often try to structure their work around features of a product. 28 | 29 | This is rarely successful, even in a single instance. In a portfolio of 30 | documentation instances, the results are wild inconsistency. Much better is 31 | the adoption of a scheme that tries to provide an answer to the 32 | question: how to arrange documentation *in general?* 33 | 34 | In fact any orderly attempt to organise documentation into clear content 35 | categories will help improve it (for authors as well as users), by providing 36 | lists of content types. 37 | 38 | Even so, authors often find themselves needing to write particular 39 | documentation content that fails to fit well within the categories put 40 | forward by a scheme, or struggling to rewrite existing material. Often, 41 | there is a sense of arbitrariness about the structure that they find 42 | themselves working with - why this particular list of content types 43 | rather than another? And if another competing list is proposed, which to 44 | adopt? 45 | 46 | 47 | Expectations and guidance 48 | ------------------------- 49 | 50 | A clear advantage of organising material this way is that it provides both 51 | clear *expectations* (to the reader) and 52 | *guidance* (to the author). It's clear what the purpose of any particular 53 | piece of content is, it specifies how it should be written and it shows 54 | where it should be placed. 55 | 56 | .. list-table:: 57 | :widths: 16 21 21 21 21 58 | :header-rows: 1 59 | :stub-columns: 1 60 | :class: wider 61 | 62 | * - \ 63 | - :ref:`Tutorials ` 64 | - :ref:`How-to guides ` 65 | - :ref:`Reference ` 66 | - :ref:`Explanation ` 67 | * - what they do 68 | - introduce, educate, lead 69 | - guide 70 | - state, describe, inform 71 | - explain, clarify, discuss 72 | * - answers the question 73 | - "Can you teach me to...?" 74 | - "How do I...?" 75 | - "What is...?" 76 | - "Why...?" 77 | * - oriented to 78 | - learning 79 | - goals 80 | - information 81 | - understanding 82 | * - purpose 83 | - to provide a learning experience 84 | - to help achieve a particular goal 85 | - to describe the machinery 86 | - to illuminate a topic 87 | * - form 88 | - a lesson 89 | - a series of steps 90 | - dry description 91 | - discursive explanation 92 | * - analogy 93 | - teaching a child how to cook 94 | - a recipe in a cookery book 95 | - information on the back of a food packet 96 | - an article on culinary social history 97 | 98 | Each piece of content is of a kind that not only has one particular job to do, that job is also clearly distinguished 99 | from and contrasted with the other functions of documentation. 100 | 101 | 102 | Blur 103 | -------------------------- 104 | 105 | Most documentation systems and authors recognise at least some of these distinctions and try to observe them in 106 | practice. 107 | 108 | .. image:: /images/partial-collapse.png 109 | :alt: Partial collapse of the structure 110 | :class: sidebar 111 | 112 | However, there is a kind of natural affinity between each of the different forms of documentation and its 113 | neighbours on the map, and a natural tendency to blur the distinctions (that can be seen repeatedly in examples of 114 | documentation). 115 | 116 | .. list-table:: 117 | :widths: 50 25 25 118 | :stub-columns: 1 119 | 120 | * - guide action 121 | - tutorials 122 | - how-to guides 123 | * - serve the application of skill 124 | - reference 125 | - how-to guides 126 | * - contain propositional knowledge 127 | - reference 128 | - explanation 129 | * - serve the acquisition of skill 130 | - tutorials 131 | - explanation 132 | 133 | When these distinctions are allowed to blur, the different kinds of documentation bleed into each other. Writing style and content make their way into inappropriate places. It also causes structural problems, which make it even more difficult to maintain the discipline of appropriate writing. 134 | 135 | .. image:: /images/total-collapse.png 136 | :alt: Total collapse of the structure 137 | :class: sidebar 138 | 139 | In the worst case there is a complete or partial collapse of tutorials and how-to guides into each other, making it impossible to meet the needs served by either. 140 | 141 | 142 | ------------- 143 | 144 | The journey around the map 145 | -------------------------- 146 | 147 | Diátaxis is intended to help documentation better serve users in their *cycle of interaction* with a product. 148 | 149 | This phrase should not be understood too literally. It is not the case that a user must encounter the different kinds 150 | of documentation in the order *tutorials* > *how-to guides* > *technical reference* > *explanation*. In practice, 151 | an actual user may enter the documentation anywhere in search of guidance on some particular subject, and what they 152 | want to read will change from moment to moment as they use your documentation. 153 | 154 | However, the idea of a cycle of documentation needs, that proceeds through different phases, is sound and corresponds 155 | to the way that people actually do become expert in a craft. There is a sense and meaning to this ordering. 156 | 157 | .. image:: /images/map-movement.png 158 | :alt: Moving around the map 159 | :class: sidebar 160 | 161 | 162 | * *learning-oriented phase*: We begin by learning, and learning a skill means diving straight in to do it - under the 163 | guidance of a teacher, if we're lucky. 164 | * *goal-oriented phase*: Next we want to put the skill to work. 165 | * *information-oriented phase*: As soon as our work calls upon knowledge that we don't already have in our head, it 166 | requires us to consult technical reference. 167 | * *explanation-oriented phase*: Finally, away from the work, we reflect on our practice and knowledge to understand the 168 | whole. 169 | 170 | And then it's back to the beginning, perhaps for a new thing to grasp, or to penetrate deeper. 171 | -------------------------------------------------------------------------------- /quality.rst: -------------------------------------------------------------------------------- 1 | Towards a theory of quality in documentation 2 | =============================================== 3 | 4 | Diátaxis is an approach to *quality* in documentation. 5 | 6 | "Quality" is a word in danger of losing some of its meaning; it's something we 7 | all approve of, but rarely risk trying to describe in any rigorous way. We 8 | want quality in our documentation, but much less often specify what exactly 9 | what we mean by that. 10 | 11 | All the same, we can generally point to examples of "high quality 12 | documentation" when asked, and can identify lapses in quality when we see 13 | them - and more than that, we often agree when we do. This suggests that 14 | we still have a useful grasp on the notion of quality. 15 | 16 | As we pursue quality in documentation, it helps to make that grasp surer, 17 | by paying some attention to it - here, attempting to refine our grasp by 18 | positing a distinction between **functional quality** and **deep quality**. 19 | 20 | 21 | Functional quality 22 | ------------------ 23 | 24 | We need documentation to meet standards of *accuracy*, *completeness*, 25 | *consistency*, *usefulness*, *precision* and so on. We can call these 26 | aspects of its **functional quality**. Documentation that fails to meet 27 | any one of them is failing to perform one of its key functions. 28 | 29 | These properties of functional quality are all independent of each other. 30 | Documentation can be accurate without being complete. It can be complete, but 31 | inaccurate and inconsistent. It can be accurate, complete, consistent and 32 | also useless. 33 | 34 | Attaining functional quality means meeting high, objectively-measurable 35 | standards in multiple independent dimensions, consistently. It requires 36 | discipline and attention to detail, and high levels of technical skill. 37 | 38 | To make it harder for the creator of documentation, any failure to meet 39 | all of these standards is readily apparent to the user. 40 | 41 | 42 | .. _deep-quality: 43 | 44 | Deep quality 45 | ------------ 46 | There are other characteristics, that we can call **deep quality**. 47 | 48 | Functional quality is not enough, or even satisfactory on its own as an 49 | ambition. True excellence in documentation implies characteristics of quality 50 | that are not included in accuracy, completeness and so on. 51 | 52 | Think of characteristics such as: 53 | 54 | * *feeling good to use* 55 | * *having flow* 56 | * *fitting to human needs* 57 | * *being beautiful* 58 | * *anticipating the user* 59 | 60 | Unlike the characteristics of functional quality, they cannot be checked or 61 | measured, but they can still be clearly identified. When we encounter them, 62 | we usually (not always, because we need to be capable of it) recognise 63 | them. 64 | 65 | They are characteristics of *deep quality*. 66 | 67 | 68 | What's the difference? 69 | --------------------------------------------------------------- 70 | 71 | Aspects of deep quality seem to be genuinely distinct in kind from the 72 | characteristics of functional quality. 73 | 74 | Documentation can meet all the demands of functional quality, and still fail 75 | to exhibit deep quality. There are many examples of documentation that is 76 | accurate and consistent (and even very useful) but which is also awkward and 77 | unpleasant to use. 78 | 79 | It's also noticeable that while characteristics of functional quality such as 80 | completeness and accuracy are **independent** of each other, those of deep 81 | quality are hard to disentangle. *Having flow* and *anticipating the user* 82 | are aspects of each other - they are **interdependent**. It's hard to see how 83 | something could feel good to use without fitting to our needs. 84 | 85 | Aspects of functional quality can be measured - literally, with numbers, in 86 | some cases (consider completeness). That's clearly not possible with 87 | qualities such as *having flow*. Instead, such qualities can only be enquired 88 | into, interrogated. Instead of taking **measurements**, we must make 89 | **judgements**. 90 | 91 | Functional quality is **objective** - it belongs to the world. Accuracy of 92 | documentation means the extent to which it conforms to the world it’s trying 93 | to describe. Deep quality can’t be ascertained by holding something up to the 94 | world. It’s **subjective**, which means that we can assess it only in the light 95 | of the needs of the subject of experience, the human. 96 | 97 | And, deep quality is **conditional** upon functional quality. Documentation 98 | can be accurate and complete and consistent without being truly excellent - 99 | but it will never have deep quality without being accurate and complete and 100 | consistent. No user of documentation will experience it as beautiful, if it's 101 | inaccurate, or enjoy the way it anticipates their needs if it's inconsistent. 102 | The moment we run into such lapses the experience of documentation is 103 | tarnished. 104 | 105 | Finally, all of the characteristics of functional quality appear to us, as 106 | documentation creators, as burdens and **constraints**. Each one of them 107 | represents a test or challenge we might fail. Or, even if we have met 108 | one *now*, we can never rest, because the next release or update means that 109 | we'll have to check our work once again, against the thing that it's 110 | documenting. Characteristics such as anticipating needs or flow, on the other 111 | hand, represent **liberation**, the work of creativity or taste. To attain 112 | functional quality in our work, we must *conform* to constraints; to attain 113 | deep quality we must *invent*. 114 | 115 | .. list-table:: 116 | :header-rows: 1 117 | 118 | * - Functional quality 119 | - Deep quality 120 | * - independent characteristics 121 | - interdependent characteristics 122 | * - objective 123 | - subjective 124 | * - measured against the world 125 | - assessed against the human 126 | * - a condition of deep quality 127 | - conditional upon functional quality 128 | * - aspects of constraint 129 | - aspects of liberation 130 | 131 | 132 | How we recognise deep quality 133 | ----------------------------- 134 | 135 | Consider how we judge the quality of say, clothing. Clothes must have 136 | *functional quality* (they must keep us appropriately warm and dry, stand up 137 | to wear). These things are objectively measurable. You don't really need to 138 | know much about clothes to assess how well they do those things. If water gets 139 | in, or the clothing falls apart - it lacks quality. 140 | 141 | There are other characteristics of quality in clothing that can't simply be 142 | measured objectively, and to recognise those characteristics, we need to have 143 | an understanding of clothing. The quality of materials or workmanship isn't 144 | always immediately obvious. Being able to judge that an item of clothing 145 | hangs well, moves well or has been expertly shaped requires developing at 146 | least a basic eye for those things. And these are its characteristics 147 | of *deep quality*. 148 | 149 | But: even someone who can't recognise, or fails to understand, those 150 | characteristics - who cannot say *what* they are - can still recognise very 151 | well *that* the clothing is excellent, because they find it that **it feels 152 | good to wear**, because it's such that they want to wear it. No expertise is 153 | required to realise that clothing does or doesn't feel comfortable as you 154 | move in it, that it fits and moves with you well. *Your body knows it*. 155 | 156 | And it's the same in documentation. Perhaps you need to be a connoisseur to 157 | recognise *what* it is that makes some documentation excellent, but that's 158 | not necessary to be able to realise *that* it is excellent. Good 159 | documentation **feels good**; you feel pleasure and satisfaction when you use 160 | it - it feels like it fits and moves with you. 161 | 162 | The users of our documentation may or may not have the understanding to say 163 | why it's good, or where its quality lapses. They might recognise only the 164 | more obvious aspects of functional quality in it, mistaking those for its 165 | deeper excellence. That doesn't matter - it will feel good, or not, and 166 | that's what is important. 167 | 168 | But we, as its creators, need a clear and effective understanding of what 169 | makes documentation good. We need to develop our sense of it so that we 170 | recognise *what* is good about it, as well as *that* it is good. And we need 171 | to develop an understanding of how people will *feel* when they're using it. 172 | 173 | Producing work of deep quality depends on our ability to do this. 174 | 175 | 176 | Diátaxis and quality 177 | -------------------- 178 | 179 | Functional quality's obligations are met through conscientious observance of 180 | the demands of the craft of documentation. They require solid skill and 181 | knowledge of the technical domain, the ability to gather up a complete 182 | terrain into a single, coherent, consistent map of it. 183 | 184 | **Diátaxis cannot address functional quality in documentation.** It is concerned 185 | only with certain aspects of deep quality, some more than others - though if 186 | all the aspects of deep quality are tangled up in each other, then it affects 187 | all of them. 188 | 189 | 190 | Exposing lapses in functional quality 191 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 192 | 193 | Although Diátaxis cannot address, or *give* us, functional quality, it can 194 | still serve it. 195 | 196 | It works very effectively to *expose* lapses in functional quality. It's often 197 | remarked that one effect of applying Diátaxis to existing documentation is 198 | that problems in it suddenly become apparent that were obscured before. 199 | 200 | For example: the Diátaxis approach recommends that :ref:`the architecture of 201 | reference documentation should reflect the architecture of the code it 202 | documents `. This makes gaps in the documentation much 203 | more clearly visible. 204 | 205 | Or, moving explanatory verbiage out of a tutorial (in accordance with Diátaxis 206 | demands) often has the effect of highlighting a section where the reader has 207 | been left to work something out for themselves. 208 | 209 | But, as far as functional quality goes, Diátaxis principles can have only an 210 | *analytical* role. 211 | 212 | 213 | Creating deep quality 214 | ~~~~~~~~~~~~~~~~~~~~~ 215 | 216 | In deep quality on the other hand, the Diátaxis approach can do more. 217 | 218 | For example, it helps documentation *fit user needs* by describing 219 | documentation modes that are based on them; its categories exist as a 220 | response to needs. 221 | 222 | We must pay attention to the correct organisation of these categories then, 223 | and the arrangement of its material and the relationships within them, the 224 | form and language adopted in different parts of documentation - as a way 225 | of fitting to user needs. 226 | 227 | Or, in Diátaxis we are directly concerned with *flow*. In flow - whether the 228 | context is documentation or anything else - we experience a movement from one 229 | stage or state to another that seems right, unforced and in sympathy with 230 | both our concerns of the moment, and the way our minds and bodies work in 231 | general. 232 | 233 | Diátaxis preserves flow by helping prevent the kind of disruption of rhythm 234 | that occurs when something runs across our purpose and steady progress 235 | towards it (for example when a digression into explanation interrupts a 236 | how-to guide). 237 | 238 | And so on. 239 | 240 | 241 | Understanding the limits 242 | ~~~~~~~~~~~~~~~~~~~~~~~~ 243 | 244 | It's important to understand that Diátaxis can never be *all* that is 245 | required in the pursuit of deep quality. 246 | 247 | For example, while it can *help* attain beauty in documentation, at least in 248 | its overall form, it doesn't by itself *make documentation beautiful*. 249 | 250 | Diátaxis offers a set of principles - it doesn't offer a formula. It certainly 251 | cannot offer a short-cut to success, bypassing the skills and insights of 252 | disciplines such as user experience or user interaction design, or even 253 | visual design. 254 | 255 | Using Diátaxis does not guarantee deep quality. The characteristics of deep 256 | quality are forever being renegotiated, reinterpreted, rediscovered and 257 | reinvented. But what Diátaxis *can* do is lay down some conditions for the 258 | *possibility* of deep quality in documentation. 259 | 260 | -------------------------------------------------------------------------------- /reference-explanation.rst: -------------------------------------------------------------------------------- 1 | .. _reference-explanation: 2 | 3 | The difference between reference and explanation 4 | ================================================ 5 | 6 | Explanation and reference both belong to the *theory* half of the Diátaxis map - they don't contain 7 | steps to guide the reader, they contain theoretical knowledge. 8 | 9 | The difference between them is - just as in the difference between tutorials and how-to guides - the 10 | difference between the *acquisition* of skill and knowledge, and its *application*. In other words 11 | it's the distinction between *study* and *work*. 12 | 13 | 14 | A straightforward distinction, *mostly* 15 | ---------------------------------------- 16 | 17 | Mostly it's fairly straightforward to recognise whether you're dealing with one or the other. 18 | *Reference*, as a form of writing, is well understood; it's used in distinctions we make about 19 | writing from an early age. 20 | 21 | In addition, examples of writing are themselves often clearly one or the other. A tidal chart, 22 | with its tables of figures, is clearly reference material. An article that explains *why* there 23 | are tides and how they behave is self-evidently explanation. 24 | 25 | There are good rules of thumb: 26 | 27 | * **If it's boring and unmemorable** it's probably *reference*. 28 | 29 | * **Lists of things** (such as classes or methods or attributes), and **tables of information**, will generally turn out to belong in *reference*. 30 | 31 | * On the other hand **if you can imagine reading something in the bath**, probably, it's *explanation* (even if really there is no accounting for what people might read in the bath). 32 | 33 | Imagine asking a friend, while out for a walk or over a drink, **Can you 34 | tell me more about ?** - the answer or discussion that follows is 35 | most likely going to be an *explanation* of it. 36 | 37 | 38 | ... but intuition isn't reliable enough 39 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 40 | 41 | Mostly we can rely safely on intuition to manage the distinction between 42 | reference and explanations. But only *mostly* - because it's also quite easy 43 | to slip between one form and the other. 44 | 45 | It usually happens while writing reference material that starts to become expansive. For example, 46 | it's perfectly reasonable to include illustrative examples in reference (just as an encyclopaedia 47 | might contain illustrations) - but examples are fun things to develop, and it can be tempting to 48 | develop them into explanation (using them to say *why*, or show *what if*, or how it came to be). 49 | 50 | As a result one often finds explanatory material sprinkled into reference. This is bad for the 51 | reference, interrupted and obscured by digressions. But it's bad for the explanation too, because 52 | it's not allowed to develop appropriately and do its own work. 53 | 54 | 55 | Work and study 56 | -------------- 57 | 58 | The real test, though, if we're in doubt about whether something is supposed to be 59 | reference or explanation is: is this something someone would turn to while working, that is, while 60 | actually getting something done, executing a task? Or is it something they'd need once they have 61 | stepped away from the work, and want to think about it? 62 | 63 | 64 | These are two very fundamentally different *needs* of the reader, that reflect how, at that moment, 65 | the reader stands in relation to the craft in question, in a relationship of *work* or *study*. 66 | 67 | .. sidebar:: 68 | 69 | To help avoid being misled by intuition, see :ref:`compass`. 70 | 71 | **Reference** is what a user needs in order help *apply* knowledge and skill, while they 72 | are working. 73 | 74 | **Explanation** is what someone will turn to to help them *acquire* knowledge 75 | and skill - "study". 76 | 77 | 78 | Understanding those two relationships and responding to the needs in them is the key to creating 79 | effective reference and explanation. 80 | -------------------------------------------------------------------------------- /reference.rst: -------------------------------------------------------------------------------- 1 | .. _reference: 2 | 3 | Reference 4 | ========= 5 | 6 | .. rubric:: Reference guides are **technical descriptions** of the machinery and how to operate it. Reference material is **information-oriented**. 7 | 8 | =========== 9 | 10 | Reference material contains *propositional or theoretical* knowledge that a user looks to in their *work*. 11 | 12 | The only purpose of a reference guide is to describe, as succinctly as possible, and in an orderly 13 | way. Whereas the content of tutorials and how-to guides are led by needs of the user, reference 14 | material is led by the product it describes. 15 | 16 | .. image:: /images/overview-reference.png 17 | :alt: Reference - information oriented, theoretical knowledge, that serves our work 18 | :class: sidebar 19 | 20 | In the case of software, reference guides describe the software itself - APIs, classes, functions 21 | and so on - and how to use them. 22 | 23 | Your users need reference material because they need truth and certainty - firm platforms on which to stand while 24 | they work. Good technical reference is essential to provide users with the confidence to do their work. 25 | 26 | ----------- 27 | 28 | Reference as description 29 | --------------------------------- 30 | 31 | Reference material describes the machinery. It should be **austere**. One hardly *reads* reference material; 32 | one *consults* it. 33 | 34 | There should be no doubt or ambiguity in reference; it should be wholly authoritative. 35 | 36 | Reference material is like a map. A map tells you what you need to know about the territory, 37 | without having to go out and check the territory for yourself; a reference guide serves the same 38 | purpose for the product and its internal machinery. 39 | 40 | Although reference should not attempt to show how to perform tasks, it can and often needs to 41 | include a description of how something works or the correct way to use it. 42 | 43 | .. sidebar:: 44 | 45 | Unfortunately, too many software developers think that auto-generated reference material is all the 46 | documentation required. 47 | 48 | Some reference material (such as API documentation) can be generated automatically by the software 49 | it describes, which is a powerful way of ensuring that it remains faithfully accurate to the code. 50 | 51 | 52 | =============== 53 | 54 | 55 | Key principles 56 | -------------- 57 | 58 | Describe and only describe 59 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ 60 | 61 | *Neutral description* is the key imperative of technical reference. 62 | 63 | .. sidebar:: Style and form 64 | 65 | * austere and uncompromising 66 | * neutrality, objectivity, factuality 67 | * structured according to the structure of the machinery itself 68 | 69 | Unfortunately one of the hardest things to do is to describe something neutrally. It's not a natural way of communicating. What's natural on the other hand is to explain, instruct, discuss, opine, and all these things run counter to the needs of technical reference, which instead demands accuracy, precision, completeness and clarity. 70 | 71 | It can be tempting to introduce instruction and explanation, simply because description can seem too inadequate to be useful, and because we do indeed need these other things. Instead, link to how-to guides, explanation and introductory tutorials. 72 | 73 | 74 | Adopt standard patterns 75 | ~~~~~~~~~~~~~~~~~~~~~~~ 76 | 77 | **Reference material is useful when it is consistent.** Standard patterns are what allow us to use reference material effectively. Your job is to place the material that your user needs know where they expect to find it, in a format that they are familiar with. 78 | 79 | There are many opportunities in writing to delight your readers with your extensive vocabulary and command of multiple styles, but reference material is definitely not one of them. 80 | 81 | 82 | .. _respect-structure: 83 | 84 | Respect the structure of the machinery 85 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 86 | 87 | The way a map corresponds to the territory it represents helps us use the former to find our way 88 | through the latter. It should be the same with documentation: **the structure of the documentation 89 | should mirror the structure of the product**, so that the user can work their way through them 90 | at the same time. 91 | 92 | It doesn't mean forcing the documentation into an unnatural structure. What's important is that the 93 | logical, conceptual arrangement of and relations within the code should help make sense of the 94 | documentation. 95 | 96 | 97 | Provide examples 98 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 99 | 100 | **Examples** are valuable ways of providing illustration that helps readers understand reference, while avoiding the risk of becoming distracted from the job of describing. For example, an example of usage of a command can be a succinct way of illustrating it and its context, without falling into the trap of trying to explain or instruct. 101 | 102 | 103 | ============== 104 | 105 | The language of reference guides 106 | -------------------------------- 107 | 108 | Django's default logging configuration inherits Python's defaults. It's available as ``django.utils.log.DEFAULT_LOGGING`` and defined in ``django/utils/log.py`` 109 | State facts about the machinery and its behaviour. 110 | Sub-commands are: a, b, c, d, e, f. 111 | List commands, options, operations, features, flags, limitations, error messages, etc. 112 | You must use a. You must not apply b unless c. Never d. 113 | Provide warnings where appropriate. 114 | 115 | =============== 116 | 117 | Applied to food and cooking 118 | --------------------------- 119 | 120 | You might check the information on a packet of food, in order to help you make a decision about what to do. 121 | 122 | When you're looking for information - relevant facts - you do not want to be confronted by opinions, speculation, instructions or interpretation. 123 | 124 | .. image:: /images/lasagne.jpg 125 | :alt: Information on the back of a packet of lasagne 126 | :class: floated 127 | 128 | 129 | You also expect that information to be presented in standard ways, so that you - when you need to know about something's nutritional properties, how it should be stored, its ingredients, what health implications it might have - can find them quickly, and know you can rely on them. 130 | 131 | So you expect to see for example: *May contain traces of wheat*. Or: *Net weight: 1000g*. 132 | 133 | You will certainly not expect to find for example recipes or marketing claims mixed up with this information; that could be literally dangerous. 134 | 135 | The way reference material is presented on food products is so important that it's usually governed by law, and the same kind of seriousness should apply to all reference documentation. 136 | 137 | -------------------------------------------------------------------------------- /requirements.txt: -------------------------------------------------------------------------------- 1 | alabaster==0.7.13 2 | Babel==2.9.1 3 | beautifulsoup4==4.10.0 4 | certifi==2022.12.7 5 | charset-normalizer==2.0.10 6 | colorama==0.4.4 7 | docutils==0.20.1 8 | furo==2023.9.10 9 | idna==3.3 10 | imagesize==1.3.0 11 | importlib-metadata==4.10.1 12 | Jinja2==3.0.3 13 | livereload==2.6.3 14 | MarkupSafe==2.0.1 15 | packaging==21.3 16 | pyenchant==3.2.2 17 | Pygments==2.17.2 18 | pyparsing==3.0.6 19 | pytz==2021.3 20 | requests==2.27.1 21 | six==1.16.0 22 | snowballstemmer==2.2.0 23 | soupsieve==2.3.1 24 | Sphinx==7.2.1 25 | sphinx-autobuild==2021.3.14 26 | sphinx-basic-ng==1.0.0b2 27 | sphinx-reredirects==0.1.2 28 | sphinx_design==0.5.0 29 | sphinxcontrib-applehelp==1.0.2 30 | sphinxcontrib-devhelp==1.0.2 31 | sphinxcontrib-htmlhelp==2.0.0 32 | sphinxcontrib-jsmath==1.0.1 33 | sphinxcontrib-qthelp==1.0.3 34 | sphinxcontrib-serializinghtml==1.1.5 35 | sphinxcontrib-spelling==7.3.2 36 | tornado==6.1 37 | urllib3==1.26.8 38 | zipp==3.7.0 39 | -------------------------------------------------------------------------------- /spelling_wordlist.txt: -------------------------------------------------------------------------------- 1 | backend 2 | Chatbot 3 | Dataset 4 | Diátaxis 5 | Divio 6 | doesn 7 | endedness 8 | equilibria 9 | Ericsson 10 | factuality 11 | Fortran 12 | frontend 13 | hylomorphic 14 | intentioned 15 | intubations 16 | isn 17 | Jupyter 18 | Laing 19 | pre 20 | prioritize 21 | reorganized 22 | weren 23 | Zalando 24 | δῐᾰ́τᾰξῐς 25 | -------------------------------------------------------------------------------- /start-here.rst: -------------------------------------------------------------------------------- 1 | .. meta:: 2 | :description: 3 | The best way to get started with Diátaxis is by applying it to documentation problems. 4 | 5 | ======================================= 6 | Start here - Diátaxis in five minutes 7 | ======================================= 8 | 9 | .. sidebar:: 10 | 11 | Treat this website as a handbook or a toolbox that you make use of when you need it. 12 | 13 | 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. **The best way to get started with Diátaxis is by applying it** - to something, however small. 14 | 15 | 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. 16 | 17 | ------------ 18 | 19 | The four kinds of documentation 20 | =============================== 21 | 22 | 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: *tutorials*, *how-to guides*, *reference* and *explanation*. Each has a different purpose, and needs to be written in a different way. 23 | 24 | 25 | Tutorials 26 | --------- 27 | 28 | .. sidebar:: 29 | 30 | * :ref:`Tutorials in more detail ` 31 | * :ref:`Why tutorials are completely different from how-to guides ` 32 | 33 | **A tutorial is a lesson**, that takes a student by the hand through a learning experience. A tutorial is always *practical*: the user *does* 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. 34 | 35 | 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: *Let's create a simple game in Python*. 36 | 37 | *The user will learn through what they do* - not because someone has tried to teach them. 38 | 39 | 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. 40 | 41 | 42 | How-to guides 43 | ------------- 44 | 45 | .. sidebar:: 46 | 47 | * :ref:`How-to guides in more detail ` 48 | 49 | **A how-to guide addresses a real-world goal or problem**, by providing practical directions to help the user who is in that situation. 50 | 51 | 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 *work* rather than *study*. 52 | 53 | A how-to guide might be: *How to store cellulose nitrate film* (in motion picture photography) or *How to configure frame profiling* (in software). Or even: *Troubleshooting deployment problems*. 54 | 55 | 56 | Reference 57 | --------- 58 | 59 | .. sidebar:: 60 | 61 | * :ref:`Reference in more detail ` 62 | 63 | **Reference guides contain the technical description** - facts - that a user needs in order to do things correctly: accurate, complete, reliable information, free of distraction and interpretation. They contain *propositional or theoretical knowledge*, not guides to action. 64 | 65 | Like a how-to guide, reference documentation serves the user who is at *work*, and it's up to the user to be sufficiently competent to interpret and use it correctly. 66 | 67 | *Reference material is neutral.* 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 a prosecuting magistrate in a legal case. 68 | 69 | 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. 70 | 71 | 72 | Explanation 73 | ----------- 74 | 75 | .. sidebar:: 76 | 77 | * :ref:`Explanation in more detail ` 78 | * :ref:`Understanding the difference between reference and explanation ` 79 | 80 | 81 | **Explanatory guides provide context and background.** They serve the need to understand and put things in a bigger picture. Explanation joins things together, and helps answer the question *why?* 82 | 83 | Explanation often needs to circle around its subject, and approach it from different directions. It can contain opinions and take perspectives. 84 | 85 | 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. 86 | 87 | Often, writers of tutorials who are anxious that their students should *know* 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 (*Secure communication using HTTPS encryption*) for when the user is ready for it. 88 | 89 | 90 | ----------- 91 | 92 | The Diátaxis map 93 | ================ 94 | 95 | The four kinds of documentation and the relationships between them can be summarised in the Diátaxis map. 96 | 97 | .. sidebar:: 98 | 99 | * :ref:`The map in more detail ` 100 | 101 | 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. 102 | 103 | Crossing or blurring the boundaries described in the map is at the heart of a vast number of problems in documentation. 104 | 105 | .. image:: /images/diataxis.png 106 | :alt: Diátaxis 107 | 108 | 109 | ----------- 110 | 111 | The Diátaxis compass 112 | ==================== 113 | 114 | As you can see from the map: 115 | 116 | * tutorials and how-to guides are concerned with what the user *does* (**action**) 117 | * reference and explanation are about what the user *knows* (**cognition**) 118 | 119 | On the other hand: 120 | 121 | * tutorials and explanation serve the *acquistion* of skill (the user's **study**) 122 | * how-to guides and reference serve the *application* of skill (the user's **work**) 123 | 124 | But a map doesn't tell you what to *do* - it's reference. To guide your action you need a different sort of tool, in this case, a kind of Diátaxis compass. 125 | 126 | .. sidebar:: 127 | 128 | * :ref:`The compass in more detail ` 129 | 130 | The compass is useful in two different ways. 131 | 132 | When creating documentation, it helps clarify your own intentions, and helps make sure you're actually doing what you think you're doing. 133 | 134 | When looking at documentation, it helps understand what's going on in it, and makes problems stand out. 135 | 136 | 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. 137 | 138 | .. list-table:: 139 | :widths: 33 33 34 140 | :header-rows: 1 141 | :stub-columns: 0 142 | :class: wider 143 | 144 | * - If the content... 145 | - ...and serves the user's... 146 | - ...then it must belong to... 147 | * - informs action 148 | - acquisition of skill 149 | - a tutorial 150 | * - informs action 151 | - application of skill 152 | - a how-to guide 153 | * - informs cognition 154 | - application of skill 155 | - reference 156 | * - informs cognition 157 | - acquisition of skill 158 | - explanation 159 | 160 | 161 | 162 | ----------- 163 | 164 | Working 165 | ======= 166 | 167 | There is a very simple workflow for Diátaxis. 168 | 169 | .. sidebar:: 170 | 171 | :ref:`how-to-use-diataxis` 172 | 173 | 1. Consider what you see in the documentation, in front of you right now (which might be literally nothing, if you haven't started yet). 174 | 175 | 2. Ask: *is there any way in which it could be improved?* 176 | 177 | 3. Decide on *one* thing you could do to it right now, however small, that would improve it. 178 | 179 | 4. Do that thing. 180 | 181 | And then repeat. 182 | 183 | That's it. 184 | 185 | 186 | ----------- 187 | 188 | Do what you like 189 | ================ 190 | 191 | 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 *true*, 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. 192 | 193 | 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. 194 | 195 | 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.) 196 | 197 | 198 | Get started 199 | =========== 200 | 201 | At this point, you have read everything you need to get started with Diátaxis. 202 | 203 | You can read more if you want, and eventually you probably should, but *you will get the most value from the guidance in this website when you turn to it with a problem or a question*. That's when it comes alive. 204 | -------------------------------------------------------------------------------- /theory.rst: -------------------------------------------------------------------------------- 1 | Understanding Diátaxis 2 | ====================== 3 | 4 | .. epigraph:: 5 | 6 | The Grand Unified Theory of Documentation 7 | 8 | -- David Laing 9 | 10 | ---------------- 11 | 12 | The pages in this section are intended to provide some theoretical grounding for the practices Diátaxis prescribes, and to explore some of the questions it raises. 13 | 14 | Within the discipline of documentation, discourse tends towards the practical and concrete. The approach is generally heuristic: guidelines, rules of thumb, specific imperatives, principles that we know work. 15 | 16 | As practitioners, we have much to say about what to do, and how to do it and how it works, and relatively little to say about *why* it works. Our sense of the right way to do things is largely based on a combination of intuition and experience. The theoretical aspect of the discipline receives far less attention. 17 | 18 | Diátaxis aims to place documentation practice on a more rigorous theoretical footing. 19 | 20 | ---------------- 21 | 22 | In this section 23 | --------------- 24 | 25 | These pages dig deeper into the thinking that underpins Diátaxis. 26 | 27 | * :doc:`foundations` - *why* Diátaxis works 28 | * :doc:`map` - documentation in two dimensions 29 | * :doc:`quality` 30 | 31 | Common problems explored: 32 | 33 | * :doc:`tutorials-how-to` 34 | * :doc:`reference-explanation` 35 | * :doc:`complex-hierarchies` 36 | -------------------------------------------------------------------------------- /tutorials-how-to.rst: -------------------------------------------------------------------------------- 1 | .. _tutorials-how-to: 2 | 3 | The difference between a tutorial and how-to guide 4 | ================================================== 5 | 6 | In Diátaxis, tutorials and how-to guides are strongly distinguished. It’s a distinction that’s often not made; in fact 7 | the single most common conflation made in software product documentation is that between the *tutorial* and the *how-to 8 | guide*. 9 | 10 | So: what *is* the difference between tutorials and how to-guides? Why does it matter? And why do they get confused? 11 | 12 | These are all good questions. Let’s start with the last one. *If the distinction is really so important, why isn’t it 13 | more obvious?* 14 | 15 | 16 | What they have in common 17 | ---------------------------- 18 | 19 | In important respects, tutorials and how-to guides are indeed similar. They are both practical guides: they contain 20 | directions for the user to follow. They’re not there to explain or convey information. They exist to guide the user in 21 | what to *do* rather than what there is *to know or understand*. 22 | 23 | They both set out steps for the reader to follow, and they both promise that if the reader follows those steps, they’ll 24 | arrive at a successful conclusion. Neither of them make much sense except for the user who has their hands on the 25 | machinery, ready to do things. They both describe ordered sequences of actions. You can’t expect success unless you 26 | perform the actions in the right order. 27 | 28 | They are closely related, and like many close relations, can be mistaken for one another at first glance. 29 | 30 | 31 | What matters is what the user needs 32 | ------------------------------------------------ 33 | 34 | Diátaxis insists that what matters in documentation is the needs of the user, and it's by paying 35 | attention to this that we can correctly distinguish between tutorials and how-to guides. 36 | 37 | Sometimes the user is **at study**, and sometimes the user is **at work**. Documentation has to serve both those needs. 38 | 39 | A tutorial serves the needs of the user who is at study. Its obligation is *to provide a successful learning 40 | experience*. A how-to guide serves the needs of the user who is at work. Its obligation is *to help the user accomplish 41 | a task*. These are completely different needs and obligations, and they are why the distinction between tutorials and 42 | how-to guides matters: tutorials are **learning-oriented**, and how-to guides are **task-oriented**. 43 | 44 | At study and at work 45 | --------------------- 46 | 47 | We can consider this from the perspective of an actual example. Let’s say you’re in medicine: a doctor, someone who 48 | needs to acquire and apply the practical, clinical skills of their craft. 49 | 50 | As a doctor, sometimes you will be in work situations, *applying your skills*, and sometimes you will be in study 51 | situations, *acquiring skills* (all good doctors, even those with long careers behind them, continue to study to 52 | improve their skills). 53 | 54 | At study 55 | ~~~~~~~~ 56 | 57 | Early on in your training, you’ll learn how to suture a wound. You’ll start in the lab with your fellow students, at 58 | benches with small skin pads in front of you (skin pads are blocks of synthetic material in various layers that 59 | represent the epidermis, fat and other tissues. They have a similar hardness and texture to human flesh, and behave 60 | somewhat similarly when they’re cut and stitched). You’ll be provided with exactly what you need - gloves, scalpel, 61 | needle, thread and so on - and step-by-step you’ll be shown what to do, and what will happen when you do it. 62 | 63 | And then it’s your turn. You will pick up the scalpel and tentatively draw it across the top of the pad, and make an 64 | ineffectual incision into the top layer (maybe a teaching assistant will tease you, asking what this poor pad has done, 65 | that it deserves such a nasty scratch). Your neighbour will look dismayed at their own attempt, a ragged cut of wildly 66 | uneven depths that looks like something from a knife-fight. 67 | 68 | After a few attempts, with feedback and correction from the tutor, you’ll have made a more or less clean cut that 69 | mostly goes through the fat layer without cutting into the muscle beneath. Triumph! 70 | 71 | .. image:: /images/suture.jpg 72 | :alt: 73 | :class: sidebar 74 | 75 | But now you’re being asked to stitch it back up again! You’ll watch the tutor demonstrate deftly and precisely, closing 76 | the wound in the pad with a few neat, even stitches. You, on the other hand, will fumble with the thread. You will hold 77 | things in the wrong hand and the wrong way round and put them down in the wrong places. You will drop the needle. The 78 | thread will fall out. You will be told off for failing to maintain sterility. 79 | 80 | Eventually, you’ll actually get to stitch the wound. You will puncture the skin in the wrong places and tear the edges 81 | of the cut. Your final result will be an ugly scene of stretched and puckered skin and crude, untidy stitches. The 82 | teaching assistants will have some critical things to say even about parts of it that you thought you’d got right. 83 | 84 | But, *you will have stitched your first wound*. And you will come back to this lesson again and again, and bit by bit 85 | your fumbling will turn into confident practice. You will have acquired basic competence. You will have **learned by 86 | doing**. 87 | 88 | This is a tutorial. It’s a *lesson*, safely in the hands of an instructor, a teacher who looks after the interests of a 89 | pupil. 90 | 91 | At work 92 | ~~~~~~~~ 93 | 94 | Now, let’s think about the doctor at work. As a doctor at work, you are already competent. You have learned and refined 95 | clinical skills such as suturing, as well as many others, and you’re able to put them together on a daily basis to 96 | apply them to medical situations in the real world. 97 | 98 | Consider a standard appendectomy. A clinical manual will list the equipment and personnel required in the theatre. It 99 | will show how to station the members of the team, and how to lay out the required tools, stands and monitors. It will 100 | proceed step-by-step through the actions the team will need to follow, ending with the formal handover to the 101 | post-operative team. 102 | 103 | .. image:: /images/operation.jpg 104 | :alt: 105 | :class: sidebar 106 | 107 | The manual will show what incisions need to be made where, but they will depend on whether you’re performing an open or 108 | a laparoscopic procedure, whether you have pre-operative imaging to rely on or not, and so on. It will include special 109 | steps or checks to be made in the case of an infant or juvenile patient, or when converting to an open appendectomy 110 | mid-procedure. Many of the steps will be of the form *if this, then that*. 111 | 112 | Having a manual helps ensure that all the steps are done in the right order and none are omitted. As a team, you’ll 113 | check through details of a procedure to remind yourselves of key steps; sometimes you'll refer to it during the 114 | procedure itself. 115 | 116 | Even for routine surgical operations, clinical manuals contain lists of steps and checks. These manuals are how-to 117 | guides. They are not there to teach you - you already have your skills. You already know these processes. They are 118 | there to guide you safely in your clinical practice to accomplish a particular task - **they serve your work**. 119 | 120 | 121 | Understanding the distinction 122 | ------------------------------ 123 | 124 | The distinction between a lesson in medical school and a clinical manual is the distinction between a tutorial and a 125 | how-to guide. 126 | 127 | .. cssclass:: lined 128 | 129 | .. grid:: 1 2 2 2 130 | :margin: 0 131 | :padding: 0 132 | :gutter: 3 133 | 134 | .. grid-item:: 135 | 136 | A tutorial’s purpose is **to help the pupil acquire basic competence**. 137 | 138 | .. grid-item:: 139 | 140 | A how-to guide’s purpose is **to help the already-competent user perform a particular task 141 | correctly**. 142 | 143 | .. grid-item:: 144 | 145 | A tutorial **provides a learning experience**. People learn skills through practical, hands-on experience. What matters 146 | in a tutorial is what the learner *does*, and what they experience while doing it. 147 | 148 | .. grid-item:: 149 | 150 | A how-to guide **directs the user’s work**. 151 | 152 | .. grid-item:: 153 | 154 | The tutorial follows a **carefully-managed path**, starting at a given point and working to 155 | a conclusion. Along that path, the learner must have the *encounters* that the lesson 156 | requires. 157 | 158 | .. grid-item:: 159 | 160 | The how-to guide aims for a successful *result*, and guides the user along the safest, 161 | surest way to the goal, but **the path can’t be managed**: it’s the real world, and 162 | anything could appear to disrupt the journey. 163 | 164 | .. grid-item:: 165 | 166 | A tutorial **familiarises the learner** with the work: with the tools, the language, the processes and the way that 167 | what they’re working with behaves and responds, and so on. Its job is to introduce them, manufacturing a structured, 168 | repeatable encounter with them. 169 | 170 | .. grid-item:: 171 | 172 | The how-to guide can and should **assume familiarity** with them all. 173 | 174 | .. grid-item:: 175 | 176 | The tutorial takes place in a **contrived setting**, a learning environment where as much as possible is set 177 | out in advance to ensure a successful experience. 178 | 179 | .. grid-item:: 180 | 181 | A how-to guide applies to the **real world**, where you have to deal 182 | with what it throws at you. 183 | 184 | .. grid-item:: 185 | 186 | The tutorial **eliminates the unexpected**. 187 | 188 | .. grid-item:: 189 | 190 | The how-to guide must **prepare for the unexpected**, alerting the user to its possibility 191 | and providing guidance on how to deal with it. 192 | 193 | .. grid-item:: 194 | 195 | A tutorial’s path follows a single line. **It doesn’t offer choices or alternatives**. 196 | 197 | .. grid-item:: 198 | 199 | A **how-to guide will typically fork and branch**, describing different routes 200 | to the same destination: *If this, then that. In the case of ..., an alternative approach 201 | is to…* 202 | 203 | .. grid-item:: 204 | 205 | A tutorial **must be safe**. No harm should come to the learner; it must always be possible to go back to the beginning 206 | and start again. 207 | 208 | .. grid-item:: 209 | 210 | A how-to guide **cannot promise safety**; often there’s only one chance to get it right. 211 | 212 | .. grid-item:: 213 | 214 | In a tutorial, **responsibility lies with the teacher**. If the learner gets into trouble, that's the teacher's problem 215 | to put right. 216 | 217 | .. grid-item:: 218 | 219 | In a how-to guide, **the user has responsibility** for getting themselves in and out of trouble. 220 | 221 | .. grid-item:: 222 | 223 | The learner **may not even have sufficient competence to ask the questions** that a tutorial answers. 224 | 225 | .. grid-item:: 226 | 227 | A how-to guide can assume that **the user is asking the right questions in the first 228 | place**. 229 | 230 | .. grid-item:: 231 | 232 | The tutorial is **explicit about basic things** - where to do things, where to put them, how to manipulate objects. It 233 | addresses the embodied experience - in our medical example, how hard to press, how to hold an implement; in a software 234 | tutorial, it could be where to type a command, or how long to wait for a response. 235 | 236 | .. grid-item:: 237 | 238 | A how-to guide relies on this as **implicit knowledge** - even bodily knowledge. 239 | 240 | .. grid-item:: 241 | 242 | A tutorial is **concrete and particular** in its approach. It refers to the specific, known, defined tools, materials, 243 | processes and conditions that we have carefully set before the learner. 244 | 245 | .. grid-item:: 246 | 247 | The how-to guide has to take a **general** approach: many of these things will be 248 | unknowable in advance, or different in each real-world case. 249 | 250 | .. grid-item:: 251 | 252 | The tutorial **teaches general skills and principles** that later could be applied to a 253 | multitude of cases. 254 | 255 | .. grid-item:: 256 | 257 | The user following a how-to guide is doing so in order to **complete a particular task**. 258 | 259 | None of these distinctions are arbitrary. They all emerge from the distinction between **study** and **work**, which we 260 | understand as a key distinction in making sense of what the user of documentation needs. 261 | 262 | 263 | 264 | The basic and the advanced 265 | -------------------------- 266 | 267 | A common but understandable conflation is to see the difference between tutorials and how-to guides as being the difference 268 | between **the basic** and **the advanced**. 269 | 270 | After all, tutorials are for learners, while how-to guides are for already-skilled practitioners. Tutorials must cover 271 | the basics, while how-to guides have to deal with complexities that learners should not have to face. 272 | 273 | However, there’s more to the story. Consider a clinical procedure manual: it could be a manual for a basic routine 274 | procedure, of very low complexity. It could describe steps for mundane matters such as correct completion of paperwork 275 | or disposal of particular materials. *How-to guides can, do and often should cover basic procedures.* 276 | 277 | At the same time, even as a qualified doctor, you will find yourself back in training situations. Some of them may be 278 | very advanced and specialised, requiring a high level of skill and expertise already. 279 | 280 | Let’s say you’re an anaesthetist of many years’ experience, who attends a course: “Difficult neonatal intubations”. The 281 | practical part of the course will be a learning experience: a lesson, safely in the hands of the instructors, that will 282 | have you performing particular exercises to develop your skills - just as it was when years earlier, you were learning 283 | to suture your first wound. 284 | 285 | The complexity is wholly different though, and so is the baseline of skills required even to participate in the 286 | learning experience. But, it’s of the same form, and serves the same kind of need, as that much earlier lesson. 287 | 288 | It’s the same in software documentation: a tutorial can present something complex or advanced. And, a how-to guide can 289 | cover something that’s basic or well-known. The difference between the two lies in the need they serve: **the user’s 290 | study**, or **their work**. 291 | 292 | 293 | Safety and success 294 | -------------------------- 295 | 296 | Understanding these distinctions, and the reason for upholding them, is crucial to creating successful documentation. A 297 | clinical manual that conflated education with practice, that tried to teach while at the same time providing a guide to 298 | a real-world procedure would be a literally deadly document. It would kill people. 299 | 300 | In disciplines such as software documentation, we get away with a great deal, because our conflations and mistakes 301 | rarely kill anyone. However, we can cause a great deal of low-level inconvenience and unhappiness to our users, and we 302 | add to it, every single time we publish a tutorial or how-to guide that doesn’t understand whether its purpose is to 303 | help the user in their study - the acquisition of skills - or in their work - the application of skills. 304 | 305 | What’s more, we hurt ourselves too. Users don’t have to use our product. If our documentation doesn’t bring them to 306 | success - if it doesn’t meet the needs that they have at a particular stage in their cycle of interaction with our 307 | product - they will find something else that does, if they can. 308 | 309 | The conflation of tutorials and how-to guides is by no means the only one made between different kinds of 310 | documentation, but it's one of the easiest to make. It's also a particularly harmful one, because it risks getting in 311 | the way of those newcomers whom we hope to turn into committed users. For the sake of those users, and of our own 312 | product, getting the distinction right is a key to success. 313 | 314 | 315 | -------------------------------------------------------------------------------- /tutorials.rst: -------------------------------------------------------------------------------- 1 | .. _tutorials: 2 | 3 | Tutorials 4 | ========= 5 | 6 | .. rubric:: A tutorial is an **experience** that takes place under the guidance of a tutor. A tutorial is always **learning-oriented**. 7 | 8 | =========== 9 | 10 | A tutorial is a *practical activity*, in which the student learns by doing something meaningful, towards some achievable goal. 11 | 12 | A tutorial serves the user's *acquisition* of skills and knowledge - their study. Its purpose is not to help the user get something done, but to help them learn. 13 | 14 | .. image:: /images/overview-tutorials.png 15 | :alt: Tutorials - learning-oriented guides that describe practical steps and are intended to serve our study. 16 | :class: sidebar 17 | 18 | A tutorial in other words is a lesson. 19 | 20 | It's important to understand that while a student will learn by doing, what the student *does* is not necessarily what they *learn*. Through doing, they will acquire theoretical knowledge (i.e. facts), understanding, familiarity. They will learn how things relate to each other and interact, and how to interact with them. They will learn the names of things, the use of tools, workflows, concepts, commands. And so on. 21 | 22 | 23 | ================= 24 | 25 | 26 | The tutorial as a lesson 27 | ------------------------ 28 | 29 | A lesson entails a relationship between a teacher and a pupil. In all learning of this kind, *learning takes place as the pupil applies themself to tasks under the instructor's guidance*. 30 | 31 | A lesson is a *learning experience*. In a learning experience, what matters is what the learner does and what happens. By contrast, the teacher's explanations and recitations of fact are far less important. 32 | 33 | A good lesson gives the learner confidence, by showing them that they can be successful in a certain skill or with a certain product. 34 | 35 | 36 | Obligations of the teacher 37 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ 38 | 39 | .. sidebar:: 40 | 41 | It's not easy being a teacher. 42 | 43 | A lesson is a kind of contract between teacher and student, in which nearly all the responsibility falls upon the teacher. The teacher has responsibility for what the pupil is to learn, what the pupil will do in order to learn it, and for the pupil's success. Meanwhile, the only responsibility of the pupil in this contract is to be attentive and to follow the teacher's directions as closely as they can. There is no responsibility on the pupil to learn, understand or remember. 44 | 45 | At the same time, the exercise you put your pupils through must be: 46 | 47 | * *meaningful* - the pupil needs to have a sense of achievement 48 | * *successful* - the pupil needs to be able to complete it 49 | * *logical* - the path that the pupil takes through it needs to make sense 50 | * *usefully complete* - the pupil must have an encounter with all of the actions, concepts and tools they need to become familiar with 51 | 52 | 53 | The problem of tutorials 54 | ~~~~~~~~~~~~~~~~~~~~~~~~ 55 | 56 | In general, tutorials are rarely done well, partly because they are genuinely difficult to do well, and partly because they are not well understood. In software, many products lack good tutorials, or lack tutorials completely; tutorials are often conflated with how-to guides. 57 | 58 | In an ideal lesson, the teacher is present and interacts with and responds to the student, correcting their mistakes and checking their learning. In documentation, none of this is possible. 59 | 60 | .. sidebar:: 61 | 62 | Writing and maintaining tutorials can consume a remarkable amount of effort and time. 63 | 64 | It's hard enough to put together a learning experience that meets all the standards described above; in many contexts the product itself evolves rapidly, meaning that all that work needs to be done again to ensure that the tutorial still performs its required functions. 65 | 66 | You will also often find that no other part of your documentation is subject to revisions the way your tutorials are. Elsewhere in documentation, changes and improvements can generally be made discretely; in tutorials, where the end-to-end learning journey must make sense, they often cascade through the entire story. 67 | 68 | Finally, tutorials contain the additional complication of the distinction between *what is to be learned* and *what is to be done*. Not only must the creator of a tutorial have a good sense of what the user must learn, and when, they must also devise a meaningful learning journey that somehow delivers all that. 69 | 70 | 71 | ================= 72 | 73 | Key principles 74 | -------------- 75 | 76 | A tutorial is a pedagogical problem. 77 | 78 | It's not an easy problem, but neither is it a mystery. The principles outlined below - repetition, action, small steps, results early and often, concreteness and so on - are not secrets, but they are not always well understood. 79 | 80 | Still, there are straightforward, effective ways to address the problems of pedagogy in practice. 81 | 82 | .. sidebar:: Anti-pedagogical temptations 83 | 84 | * abstraction, generalisation 85 | * explanation 86 | * choices 87 | * information 88 | 89 | The first rule of teaching is simply: **don't try to teach**. Your job, as a teacher, is to provide the learner with an experience that will allow them to learn. A teacher inevitably feels a kind of anxiety to impart knowledge and understanding, but if you give into it and try to teach by telling and explaining, you will jeopardise the learning experience. 90 | 91 | Instead, *allow learning to take place*, and trust that it will. Give your learner things to *do*, through which they can learn. Only your pupil can learn. Sadly, however much you desire it, you will not be able to learn for your pupil. You cannot make them learn. All you can do is make it so *they* can learn. 92 | 93 | 94 | Show the learner where they'll be going 95 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 96 | 97 | It's important to allow the learner to form an idea of what they will achieve right from the start. As well as helping to set expectations, it allows them to see themselves building towards the completed goal as they work. 98 | 99 | Providing the picture the learner needs in a tutorial can be as simple as informing them at the outset: *In this tutorial we will create and deploy a scalable web application. Along the way we will encounter containerisation tools and services.* 100 | 101 | This is not the same as saying: *In this tutorial you will learn...* - which is presumptuous and a very poor pattern. 102 | 103 | 104 | Deliver visible results early and often 105 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 106 | 107 | Your learner is probably doing new and strange things that they don't fully understand. Understanding comes from being able to make connections between causes and effects, so let them see the results and make the connections rapidly and repeatedly. Each one of those results should be something that the user can see as meaningful. 108 | 109 | Every step the learner follows should produce a comprehensible result, however small. 110 | 111 | 112 | Maintain a narrative of the expected 113 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 114 | 115 | At every step of a tutorial, the user experiences a moment of anxiety: will this action produce the correct result? Part of the work of a successful tutorial is to keep providing feedback to the learner that they are indeed on the right path. 116 | 117 | Keep up a narrative of expectations: "You will notice that ..."; "After a few moments, the server responds with ...". Show the user actual example output, or even the exact expected output. 118 | 119 | If you know know in advance what the likely signs of going wrong are, consider flagging them: "If the output doesn't show ..., you have probably forgotten to ...". 120 | 121 | It's helpful to prepare the user for possibly surprising actions: "The command will probably return several hundred lines of logs in your terminal." 122 | 123 | 124 | Point out what the learner should notice 125 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 126 | 127 | Learning requires reflection. This happens at multiple levels and depths, but one of the first is when the learner observes the signs in their environment. In a lesson, a learner is typically too focused on what they are doing to notice them, unless they are prompted by the teacher. 128 | 129 | Your job as teacher is to close the loops of learning by pointing things out, in passing, as the lesson moves along. This can be as simple as pointing out how a command line prompt changes, for example. 130 | 131 | Observing is an active part of a craft, not a merely passive one. It means paying attention to the environment, a skill in itself. It's often neglected. 132 | 133 | 134 | Target *the feeling of doing* 135 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 136 | 137 | In all skill or craft, the accomplished practitioner experiences a *feeling of doing*, a joined-up purpose, action, thinking and result. 138 | 139 | As skill develops, it flows in a confident rhythm and becomes a kind of pleasure. It's the pleasure of walking, for example. 140 | 141 | .. sidebar:: 142 | 143 | Pay attention to your own *feeling of doing* in your work. What is it like to perform a particular operation? 144 | 145 | Your learner's skill depends upon their discovering this feeling, and its becoming a pleasure. 146 | 147 | Your challenge as the creator of a tutorial is to ensure that its tasks tie together purpose and action so they become a cradle for this feeling. 148 | 149 | 150 | Encourage and permit repetition 151 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 152 | 153 | Learners will return to and repeat an exercise that gives them success, for the pleasure they find in getting the expected result. Doing so reaffirms to them that they can do it, and that it works. 154 | 155 | Repetition is a key to establishing the feeling to doing; being at home with that feeling is a foundational layer of learning. 156 | 157 | .. sidebar:: 158 | 159 | Repetition is not the best teacher - sometimes it's the *only* teacher. 160 | 161 | In your tutorial, try to make it possible for a particular step and result to be repeated. This can be difficult, for example in operations that are not reversible (making it hard to go back to a previous step) - but seek it wherever you can. Watching a user follow a tutorial, you may often be amazed to see how often they choose to repeat a step. They are doing it just to see that the same thing really does happen again. 162 | 163 | 164 | Ruthlessly minimise explanation 165 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 166 | 167 | *A tutorial is not the place for explanation.* In a tutorial, the user is focused on correctly following your directions and getting the expected results. *Later*, when they are ready, they will seek explanation, but right now they are concerned with *doing*. Explanation distracts their attention from that, and blocks their learning. 168 | 169 | For example, it's quite enough to say something like: *We're using HTTPS because it's more secure.* There is a place for extended discussion and explanation of HTTPS, but not now. Instead, provide a link or reference to that explanation, so that it's available, but doesn't get in the way. 170 | 171 | .. sidebar:: 172 | 173 | Explanation is only pertinent at the moment the *user* wants it. It is not for the documentation author to decide. 174 | 175 | Explanation is one of the hardest temptations for a teacher to resist; even experienced teachers find it difficult to accept that their students' learning does not depend on explanation. This is perfectly natural. Once we have grasped something, we rely on the power of abstraction to frame it to ourselves - and that's how we want to frame it to others. Understanding means grasping general ideas, and abstraction is the logical form of understanding - but these are not what we need in a tutorial, and it's not how successful learning or teaching works. 176 | 177 | One must see it for oneself, to see the focused attention of a student dissolve into air, when a teacher's well-intentioned explanation breaks the magic spell of learning. 178 | 179 | 180 | ... and focus on the concrete 181 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 182 | 183 | In a learning situation, your student is in the moment, a moment composed of concrete things. You are responsible for setting up and maintaining the student's flow, from one concrete action and result to another. 184 | 185 | Focus on *this* problem, *this* action, *this* result, in such a way that you lead the learner from step to concrete step. 186 | 187 | It might seem that by maintaining focus on the concrete and particular that you deny the student the opportunity to see or grasp the larger general patterns, but the contrary is true. The one thing our minds do spectacularly well is to perceive general patterns from concrete examples. All learning moves in one direction: from the concrete and particular, towards the general and abstract. The latter *will* emerge from the former. 188 | 189 | 190 | Ignore options and alternatives 191 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 192 | 193 | Your job is to guide the learner to a successful conclusion. There may be many interesting diversions along the way (different options for the command you're using, different ways to use the API, different approaches to the task you're describing) - ignore them. *Your guidance needs to remain focused on what's required to reach the conclusion*, and everything else can be left for another time. 194 | 195 | Doing this helps keep your tutorial shorter and crisper, and saves both you and the reader from having to do extra cognitive work. 196 | 197 | 198 | Aspire to perfect reliability 199 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 200 | 201 | All of the above are general principles of pedagogy, but there is a special burden on the creator of a tutorial. 202 | 203 | A tutorial must inspire confidence. Confidence can only be built up layer by layer, and is easily shaken. At every stage, when you ask your student to do something, they must see the result you promise. A learner who follows your directions and doesn't get the expected results will quickly lose confidence, in the tutorial, the tutor and themselves. 204 | 205 | .. sidebar:: 206 | 207 | You are required to be present, but condemned to be absent. 208 | 209 | A teacher who's there with the learner can rescue them when things go wrong. In a tutorial, you can't do that. Your tutorial ought to be so well constructed that things *can't* go wrong, that your tutorial works for every user, every time. 210 | 211 | It's hard work to create a reliable experience, but that is what you must aspire to in creating a tutorial. 212 | 213 | Your tutorial will have flaws and gaps, however carefully it is written. You won't discover them all by yourself, you will have to rely on users to discover them for you. The only way to learn what they are is by finding out what actually happens when users do the tutorial, through extensive testing and observation. 214 | 215 | 216 | ============== 217 | 218 | The language of tutorials 219 | ------------------------- 220 | 221 | We ... 222 | The first-person plural affirms the relationship between tutor and learner: you are not alone; we are in this together. 223 | In this tutorial, we will ... 224 | Describe what the learner will accomplish. 225 | First, do x. Now, do y. Now that you have done y, do z. 226 | No room for ambiguity or doubt. 227 | We must always do x before we do y because... (see Explanation for more details). 228 | Provide minimal explanation of actions in the most basic language possible. Link to more detailed explanation. 229 | The output should look something like ... 230 | Give your learner clear expectations. 231 | Notice that ... Remember that ... Let's check ... 232 | Give your learner plenty of clues to help confirm they are on the right track and orient themselves. 233 | You have built a secure, three-layer hylomorphic stasis engine... 234 | Describe (and admire, in a mild way) what your learner has accomplished. 235 | 236 | 237 | =============== 238 | 239 | Applied to food and cooking 240 | --------------------------- 241 | 242 | .. image:: /images/anselmo.jpg 243 | :alt: A child proudly showing a dish he has helped prepare 244 | 245 | Someone who has had the experience of teaching a child to cook will understand what matters in a tutorial, and just as importantly, the things that don't matter at all. 246 | 247 | It really doesn't matter what the child makes, or how correctly they do it. The value of a lesson lies in what the child gains, not what they produce. 248 | 249 | Success in a cooking lesson with a child is not the culinary outcome, or whether the child can now repeat the processes on their own. Success is when the child acquires the knowledge and skills you were hoping to impart. 250 | 251 | It's a crucial condition of this that the child discovers pleasure in the experience of being in the kitchen with you, and wants to return to it. Learning a skill is never a once and for all matter. Repetition is always required. 252 | 253 | Meanwhile, the cooking lesson might be framed around the idea of learning how to prepare a particular dish, but what we actually need the child to learn might be things like: *that we wash our hands before handling food*; *how to hold a knife*; *why the oil must be hot*; *what this utensil is called*, *how to time and measure things*. 254 | 255 | The child learns all this by working alongside you in the kitchen; in its own time, at its own pace, **through the activities** you do together, and not from the things you say or show. 256 | 257 | With a young child, you will often find that the lesson suddenly has to end before you'd completed what you set out to do. This is normal and expected; children have short attention spans. But as long as the child managed to achieve something - however small - and enjoyed doing it, it will have laid down something in the construction of its technical expertise, that can be returned to and built upon next time. 258 | --------------------------------------------------------------------------------