├── .gitignore ├── Makefile ├── README.rst ├── adoption.rst ├── conf.py ├── explanation.rst ├── how-to-guides.rst ├── images ├── anselmo.jpg ├── collapse.png ├── divio-explanation-example.png ├── django-how-to-example.png ├── django-reference-example.png ├── django-tutorial-example.png ├── ginger.jpg ├── mcgee.jpg ├── overview.png └── recipe.jpg ├── index.rst ├── introduction.rst ├── make.bat ├── reference.rst ├── requirements.txt ├── structure.rst └── tutorials.rst /.gitignore: -------------------------------------------------------------------------------- 1 | /*env*/ 2 | _build 3 | .DS_Store 4 | __pycache__ 5 | .idea/ 6 | _templates/ 7 | -------------------------------------------------------------------------------- /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 dirhtml . _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 | :orphan: 2 | 3 | The documentation system 4 | ======================== 5 | 6 | A comprehensive and practical system that can help maintainers of product documentation. 7 | 8 | Published at https://documentation.divio.com 9 | 10 | Author: Daniele Procida 11 | -------------------------------------------------------------------------------- /adoption.rst: -------------------------------------------------------------------------------- 1 | .. _adoption: 2 | 3 | Who is using the system? 4 | ======================== 5 | 6 | .. sidebar:: Not listed here? 7 | 8 | If you're using the system, or are in the process of adopting it, please let us know if you'd like to be 9 | listed here. 10 | 11 | This is an incomplete list of projects, products and organisations that have adopted the system in their own 12 | bodies of documentation. In some cases the adoption remains partial or is still a work in progress. 13 | 14 | * `BrachioGraph `_, the cheapest, simplest pen-plotter 15 | * `BeeWare `_, the write-once-deploy-anywhere project, for `Toga `_, 16 | `Briefcase `_, `Rubicon `_ and `Rubicon Java 17 | `_. 18 | * Bosch (internal) 19 | * `Ciw `_, the discrete event simulation library 20 | * `Cloudflare Workers docs `_ (related article, `New and 21 | improved Workers Docs `_) 22 | * `Divio `_ 23 | * `Django `_ 24 | * `django CMS `_ 25 | * `edo `_, a library for Evolutionary Dataset Optimisation 26 | * Ericsson (internal) 27 | * `Gensim `_, `How to Author Gensim Documentation 28 | `_ 29 | * `StrongLoop/LoopBack `_ by IBM 30 | * `Lisk `_ 31 | * `Matching `_, a games theory resource allocation library 32 | * `NashPy `_, a Python mathematical library for computing Nash equilibria 33 | * `nbchkr `_, a system for assessing students' assignments in Jupyter Notebooks 34 | * `NumPy `_, the scientific Python library (related article, `Documentation as a way to 35 | build Community `_) 36 | * `PDFminer.six `_ 37 | * `PostgREST `_ 38 | * `PIconnect `_ 39 | * Tesla Motors (internal) 40 | * `WebAccess/DMP `_ 41 | * Zalando (internal) 42 | 43 | 44 | Other mentions and references of interest 45 | ----------------------------------------- 46 | 47 | * `Django Axes proposal `_ 48 | * `GitLab `_, `GitLab's Data 49 | Team documentation guide 50 | `_ 51 | * `Julia language proposal `_ 52 | * `Why You Should Document Your Work As a Data Scientist `_ 53 | * `Koninglijke Biblioteek (National Library of the Netherlands) research software lab 54 | `_ 55 | * `Tutorials in Jenkins user documentation 56 | `_ 57 | * `TYPO3 `_ 58 | -------------------------------------------------------------------------------- /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 | project = 'Documentation system' 21 | copyright = '2020, 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 = [ 31 | ] 32 | 33 | # Add any paths that contain templates here, relative to this directory. 34 | templates_path = ['_templates'] 35 | 36 | # List of patterns, relative to source directory, that match files and 37 | # directories to ignore when looking for source files. 38 | # This pattern also affects html_static_path and html_extra_path. 39 | exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'env'] 40 | 41 | 42 | # -- Options for HTML output ------------------------------------------------- 43 | 44 | # The theme to use for HTML and HTML Help pages. See the documentation for 45 | # a list of builtin themes. 46 | # 47 | try: 48 | import divio_docs_theme 49 | except ModuleNotFoundError: 50 | html_theme = 'alabaster' 51 | else: 52 | html_theme = 'divio_docs_theme' 53 | html_theme_path = [divio_docs_theme.get_html_theme_path()] 54 | html_theme_options = { 55 | 'show_cloud_banner': True, 56 | 'cloud_banner_markup': """ 57 |
58 | Cloud deployment by Divio 59 | 60 |

There's a better, faster, easier way to develop, deploy and manage web applications.

61 | Find out more at Divio 62 |
63 | """, 64 | } 65 | 66 | 67 | # Add any paths that contain custom static files (such as style sheets) here, 68 | # relative to this directory. They are copied after the builtin static files, 69 | # so a file named "default.css" will overwrite the builtin "default.css". 70 | html_static_path = ['_static'] 71 | 72 | master_doc = 'index' 73 | 74 | 75 | -------------------------------------------------------------------------------- /explanation.rst: -------------------------------------------------------------------------------- 1 | .. _explanation: 2 | 3 | Explanation 4 | ================= 5 | 6 | Explanation, or discussions, *clarify and illuminate a particular topic*. They broaden the documentation’s coverage of a topic. 7 | 8 | They are **understanding-oriented**. 9 | 10 | Explanations can equally well be described as *discussions*; they are discursive in nature. They are a chance for the documentation to relax and step back from the software, taking a wider view, illuminating it from a higher level or even from different perspectives. You might imagine a discussion document being read at leisure, rather than over the code. 11 | 12 | This section of documentation is rarely explicitly created, and instead, snippets of explanation are scattered amongst other sections. Sometimes, the section exists, but has a name such as *Background* or *Other notes* or *Key topics* - these names are not always useful. 13 | 14 | Discussions are less easy to create than it might seem - things that are straightforward to explain when you have the starting-point of someone’s question are less easy when you have a blank page and have to write down something about it. 15 | 16 | A topic isn’t defined by a specific task you want to achieve, like a how-to guide, or what you want the user to learn, like a tutorial. It’s not defined by a piece of the machinery, like reference material. It’s defined by what **you** think is a reasonable area to try to cover at one time, so the division of topics for discussion can sometimes be a little arbitrary. 17 | 18 | Analogy from cooking 19 | -------------------- 20 | 21 | .. image:: /images/mcgee.jpg 22 | :alt: 'a child cooking' 23 | :align: right 24 | :width: 379 25 | 26 | Think about a work that discusses food and cooking in the context of history, science and technology. It's *about* 27 | cooking and the kitchen. 28 | 29 | It doesn't teach, it's not a collection of recipes, and it doesn't just describe. 30 | 31 | Instead, it analyses, considers things from multiple perspectives. It might explain why it is we now do things the way we do, or 32 | even describe bad ways of doing things, or obscure alternatives. 33 | 34 | It deepens our knowledge and makes it richer, even if it isn't knowledge we can actually apply in any practical sense - but it doesn't need to be, in order to be valuable. 35 | 36 | It's something we might read at our leisure, away from the kitchen itself, when we want 37 | to think about cooking at a higher level, and to understand more about the subject. 38 | 39 | 40 | How to write a good explanation 41 | ---------------------------------- 42 | 43 | Provide context 44 | ~~~~~~~~~~~~~~~ 45 | 46 | **Explanations are the place for background and context** - for example, *Web forms and how they are handled in Django*, or *Search in django CMS*. 47 | 48 | They can also explain *why* things are so - design decisions, historical reasons, technical constraints. 49 | 50 | 51 | Discuss alternatives and opinions 52 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 53 | 54 | **Explanation can consider alternatives**, or multiple different approaches to the same question. For example, in an article on Django deployment, it would be appropriate to consider and evaluate different web server options, 55 | 56 | Discussions can even consider and weigh up contrary *opinions* - for example, whether test modules should be in a package directory, or not. 57 | 58 | 59 | Don't instruct, or provide technical reference 60 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 61 | 62 | **Explanation should do things that the other parts of the documentation do not.** It’s not the place of an explanation to instruct the user in how to do something. Nor should it provide technical description. These functions of documentation are already taken care of in other sections. 63 | 64 | 65 | Example from Divio's documentation 66 | ---------------------------------- 67 | 68 | Have a look at `our explanation section `_ (titled "Background" - 69 | the name is not important as long as the purpose is clear). 70 | 71 | .. image:: /images/divio-explanation-example.png 72 | :alt: 'Django explanation example' 73 | :align: right 74 | :width: 379 75 | 76 | These articles don’t teach anything. They don’t tell the user what to do. They aren’t reference guides. They just 77 | discuss particular topics. The user doesn’t *need* to know about (for example) caching or CDN or how we manage 78 | environment variables in order to use the platform or achieve any particular task, but the time is likely to come when 79 | someone's experience and use of the platform will be improved by having a clearer, better, deeper understanding of 80 | those things. 81 | 82 | These articles provide the bigger picture, the context. Users are human beings; maybe they don’t strictly need to know 83 | why we do a certain thing a certain way, but knowing it might well provide them with a kind of satisfaction and comfort 84 | that makes them a happier user of the product. 85 | -------------------------------------------------------------------------------- /how-to-guides.rst: -------------------------------------------------------------------------------- 1 | .. _how-to: 2 | 3 | How-to guides 4 | ============= 5 | 6 | How-to guides take the reader through the steps required to solve a real-world problem. 7 | 8 | They are recipes, directions to achieve a specific end - for example: *how to create a web form*; *how to plot a three-dimensional data-set*; *how to enable LDAP authentication*. 9 | 10 | They are wholly **goal-oriented**. 11 | 12 | **How-to guides are wholly distinct from tutorials** and must not be confused with them: 13 | 14 | * A tutorial is what you decide a beginner needs to know. 15 | * A how-to guide is an answer to a question that only a user with some experience could even formulate. 16 | 17 | In a how-to guide, you can assume some knowledge and understanding. You can assume that the user already knows how to do basic things and use basic tools. 18 | 19 | Unlike tutorials, how-to guides in software documentation tend to be done fairly well. They’re also fun and easy to write. 20 | 21 | 22 | Analogy from cooking 23 | -------------------- 24 | 25 | .. image:: /images/recipe.jpg 26 | :alt: 'a recipe' 27 | 28 | 29 | Think about a recipe, for preparing something to eat. 30 | 31 | A recipe has a clear, defined end. It addresses a specific question. It shows someone - who can be assumed to have some basic knowledge already - how to achieve something. 32 | 33 | Someone who has never cooked before can't be expected to follow a recipe with success, so a recipe is not a substitute for a cooking lesson. At the same time, someone who reads a recipe would be irritated to find that it tries to teach basics that they know already, 34 | or contains irrelevant discussion of the ingredients. 35 | 36 | 37 | How to write good how-to guides 38 | ------------------------------- 39 | 40 | Provide a series of steps 41 | ~~~~~~~~~~~~~~~~~~~~~~~~~ 42 | 43 | **How-to guides must contain a list of steps, that need to be followed in order** (just like tutorials to). You don’t have to start at the very beginning, just at a reasonable starting point. How-to guides should be reliable, but they don’t need to have the cast-iron repeatability of a tutorial. 44 | 45 | 46 | Focus on results 47 | ~~~~~~~~~~~~~~~~~~~~ 48 | 49 | **How-to guides must focus on achieving a practical goal.** Anything else is a distraction. As in tutorials, detailed explanations are out of place here. 50 | 51 | 52 | Solve a particular problem 53 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ 54 | 55 | **A how-to guide must address a specific question or problem**: *How do I …?* 56 | 57 | This is one way in which how-to guides are distinct from tutorials: when it comes to a how-to guide, the reader can be assumed to know *what* they should achieve, but don’t yet know *how* - whereas in the tutorial, *you* are responsible for deciding what things the reader needs to know about. 58 | 59 | 60 | Don't explain concepts 61 | ~~~~~~~~~~~~~~~~~~~~~~~ 62 | 63 | **A how-to guide should not explain things.** It’s not the place for discussions of that kind; they will simply get in the way of the action. If explanations are important, link to them. 64 | 65 | 66 | Allow for some flexibility 67 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ 68 | 69 | **A how-to guide should allow for slightly different ways of doing the same thing.** It needs just enough flexibility in it that the user can see how it will apply to slightly different examples from the one you describe, or understand how to adapt it to a slightly different system or configuration from the one you’re assuming. Don’t be so specific that the guide is useless for anything except the exact purpose you have in mind. 70 | 71 | 72 | Leave things out 73 | ~~~~~~~~~~~~~~~~ 74 | 75 | **Practical usability is more valuable than completeness.** Tutorials need to be complete, end-to-end guides; how-to guides do not. They can start and end where it seems appropriate to you. They don’t need to mention everything that there is to mention either, just because it is related to the topic. A bloated how-to guide doesn’t help the user get speedily to their solution. 76 | 77 | 78 | Name guides well 79 | ~~~~~~~~~~~~~~~~ 80 | 81 | **The title of a how-to document should tell the user exactly what it does.** *How to create a class-based view* is a good title. *Creating a class-based view* or worse, *Class-based views*, are not. 82 | 83 | 84 | Example from Divio's documentation 85 | ---------------------------------- 86 | 87 | Have a look at `our how-to guides `_. 88 | 89 | .. image:: /images/django-how-to-example.png 90 | :alt: 'Django how-to example' 91 | :align: right 92 | :width: 379 93 | 94 | Each one of these is an answer to a question, or problem: *how do I...?* Each title can clearly be preceded by the 95 | words “How to”. Each one is a recipe, that takes you through the steps required to complete a specific task. 96 | 97 | Although both the tutorials and the how-to guides serve the needs of the user, the tutorials are led by the author who 98 | knows what the user needs to know, while the how-to guides are led by the user who asks the questions. 99 | -------------------------------------------------------------------------------- /images/anselmo.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/xiaolai/documentation-system/12d007484894172f07c57978e271909797fb49ee/images/anselmo.jpg -------------------------------------------------------------------------------- /images/collapse.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/xiaolai/documentation-system/12d007484894172f07c57978e271909797fb49ee/images/collapse.png -------------------------------------------------------------------------------- /images/divio-explanation-example.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/xiaolai/documentation-system/12d007484894172f07c57978e271909797fb49ee/images/divio-explanation-example.png -------------------------------------------------------------------------------- /images/django-how-to-example.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/xiaolai/documentation-system/12d007484894172f07c57978e271909797fb49ee/images/django-how-to-example.png -------------------------------------------------------------------------------- /images/django-reference-example.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/xiaolai/documentation-system/12d007484894172f07c57978e271909797fb49ee/images/django-reference-example.png -------------------------------------------------------------------------------- /images/django-tutorial-example.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/xiaolai/documentation-system/12d007484894172f07c57978e271909797fb49ee/images/django-tutorial-example.png -------------------------------------------------------------------------------- /images/ginger.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/xiaolai/documentation-system/12d007484894172f07c57978e271909797fb49ee/images/ginger.jpg -------------------------------------------------------------------------------- /images/mcgee.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/xiaolai/documentation-system/12d007484894172f07c57978e271909797fb49ee/images/mcgee.jpg -------------------------------------------------------------------------------- /images/overview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/xiaolai/documentation-system/12d007484894172f07c57978e271909797fb49ee/images/overview.png -------------------------------------------------------------------------------- /images/recipe.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/xiaolai/documentation-system/12d007484894172f07c57978e271909797fb49ee/images/recipe.jpg -------------------------------------------------------------------------------- /index.rst: -------------------------------------------------------------------------------- 1 | .. raw:: html 2 | 3 | 7 | 8 | 9 | The documentation system 10 | ================================================ 11 | 12 | .. rst-class:: quote 13 | 14 | The Grand Unified Theory of Documentation 15 | 16 | .. rst-class:: attribution 17 | 18 | \- David Laing 19 | 20 | There is a secret that needs to be understood in order to write good software documentation: there isn’t one 21 | thing called *documentation*, there are four. 22 | 23 | They are: *tutorials*, *how-to guides*, *technical reference* and *explanation*. They represent four different 24 | purposes or functions, and require four different approaches to their creation. Understanding the implications of 25 | this will help improve most documentation - often immensely. 26 | 27 | 28 | About the system 29 | ---------------- 30 | 31 | .. image:: /images/overview.png 32 | :alt: 'overview of the documentation system' 33 | 34 | 35 | The documentation system outlined here is a simple, comprehensive and nearly universally-applicable scheme. It 36 | is proven in practice across a wide variety of fields and applications. 37 | 38 | There are some very simple principles that govern documentation that are very rarely if ever spelled out. They seem 39 | to be a secret, though they shouldn’t be. 40 | 41 | If you can put these principles into practice, **it will make your documentation better and your project, product 42 | or team more successful** - that’s a promise. 43 | 44 | :ref:`The system is widely adopted ` for large and small, open and proprietary documentation projects. 45 | 46 | 47 | .. toctree:: 48 | :maxdepth: 0 49 | :hidden: 50 | 51 | introduction 52 | tutorials 53 | how-to-guides 54 | reference 55 | explanation 56 | structure 57 | adoption 58 | 59 | 60 | Video presentation 61 | ------------------ 62 | 63 | If you'd prefer to watch a video covering this topic, here is it (courtesy of PyCon Australia 2017). 64 | 65 | .. raw:: html 66 | 67 | 68 | -------------------------------------------------------------------------------- /introduction.rst: -------------------------------------------------------------------------------- 1 | .. raw:: html 2 | 3 | 7 | 8 | 9 | Introduction 10 | ============ 11 | 12 | The problem and the solution 13 | ------------------------------ 14 | 15 | The problem it solves 16 | ~~~~~~~~~~~~~~~~~~~~~ 17 | 18 | It doesn’t matter how good your product is, because **if its documentation is not good enough, people will not use it**. Even if they have to use it because they have no choice, without good documentation, they won’t use it effectively or the way 19 | you’d like them to. 20 | 21 | Nearly everyone understands this. Nearly everyone knows that they need good documentation, and **most people try to create good documentation**. And **most people fail**. 22 | 23 | Usually, it’s not because they don’t try hard enough. Usually, it’s because they are not doing it the right way. 24 | 25 | This system is a way to make your documentation better, not by working harder at it, but by doing it the right way. **The right way is the easier way** - easier to write, and easier to maintain. 26 | 27 | 28 | The 'secret' 29 | ~~~~~~~~~~~~ 30 | 31 | It's not actually a secret and it certainly shouldn't be: documentation needs to include and be structured around its **four different functions**: *tutorials*, *how-to guides*, *technical reference* and *explanation*. Each of them **requires a distinct mode of writing**. People working with software need these four different kinds of documentation at different times, in different circumstances - so software usually needs them all, and they should all be integrated into your documentation. 32 | 33 | And documentation needs to be explicitly structured around them, and they all must be kept separate and distinct from each other. 34 | 35 | .. list-table:: 36 | :widths: 16 21 21 21 21 37 | :header-rows: 1 38 | 39 | * - \ 40 | - :ref:`Tutorials ` 41 | - :ref:`How-to guides ` 42 | - :ref:`Reference ` 43 | - :ref:`Explanation ` 44 | * - *oriented to* 45 | - learning 46 | - a goal 47 | - information 48 | - understanding 49 | * - *must* 50 | - allow the newcomer to get started 51 | - show how to solve a specific problem 52 | - describe the machinery 53 | - explain 54 | * - *its form* 55 | - a lesson 56 | - a series of steps 57 | - dry description 58 | - discursive explanation 59 | * - *analogy* 60 | - teaching a small child how to cook 61 | - a recipe in a cookery book 62 | - a reference encyclopaedia article 63 | - an article on culinary social history 64 | 65 | This division makes it obvious to both author and reader what material, and what *kind* of material, goes where. It tells the 66 | author **how to write**, and **what to write**, and **where to write it**. It saves the author from wasting a great deal of time 67 | trying to wrestle the information they want to impart into a shape that makes sense, because **each of these kinds of 68 | documentation has only one job**. 69 | 70 | In fact, it’s extremely hard to maintain good documentation that doesn’t implicitly or explicitly recognise the quadrants of this scheme. The demands of each kind are different from those of the others, so **any attempt at documentation that fails to maintain this structure suffers**, as it’s pulled in different directions at once. 71 | 72 | Once you understand the structure, it becomes a very useful tool for analysing existing documentation, and understanding what needs to be done to improve it. 73 | 74 | In the following sections, each of these four parts is dealt with in detail. 75 | 76 | 77 | Making documentation work 78 | ------------------------- 79 | 80 | For authors 81 | ~~~~~~~~~~~ 82 | 83 | One of the biggest headaches that documentation maintainers have to deal with is not having a clear picture of what they should be doing. They write and rewrite, but find it hard to make it fit together in satisfactory ways. 84 | 85 | This structure resolves those questions by making clear distinctions and separations. They make documentation that is easier to write and maintain, that’s easier to use and to find one's way around in. 86 | 87 | The documentation doesn’t write itself - but it’s now possible to write it without also having to wrestle with poor fit, or unclear scope or doubt about what should be included or what style to adopt. It becomes much clearer what to write, how to write it, and where to put it. 88 | 89 | 90 | For readers 91 | ~~~~~~~~~~~ 92 | 93 | It serves users better, because for all the different phases in the cycle of their interaction with the software they will find the right kind of documentation, that serves the needs of that moment. 94 | 95 | Writing documentation that explicitly and distinctly addresses each of the four quadrants helps the software attract and keep more users, who will use it more effectively - and that is one of the things the creators of software want most of all. 96 | -------------------------------------------------------------------------------- /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 | -------------------------------------------------------------------------------- /reference.rst: -------------------------------------------------------------------------------- 1 | .. _reference: 2 | 3 | Reference guides 4 | ================= 5 | 6 | Reference guides are *technical descriptions of the machinery* and how to operate it. 7 | 8 | Reference guides have one job only: to describe. They are code-determined, because ultimately that's what they describe: key classes, functions, APIs, and so they should list things like functions, fields, attributes and methods, and set out how to use them. 9 | 10 | Reference material is **information-oriented**. 11 | 12 | By all means technical reference can contain examples to illustrate usage, but it should not attempt to explain basic concepts, or how to achieve common tasks. 13 | 14 | Reference material should be **austere and to the point**. 15 | 16 | Note that description **does** include basic description of how to use the machinery - how to instantiate a particular class, or invoke a certain method, for example, or precautions that must be taken when passing something to a function. However this is simply part of its function as technical reference, and emphatically **not** to be confused with a how-to guide - *describing correct usage of software* (technical reference) is not the same as *showing how to use it to achieve a certain end* (how-to documentation). 17 | 18 | For some developers, reference guides are the only kind of documentation they can imagine. They already understand their software, they know how to use it. All they can imagine that other people might need is technical information about it. 19 | 20 | Reference material tends to be written well. It can even - to some extent - be generated automatically, but this is never sufficient on its own. 21 | 22 | Analogy from cooking 23 | -------------------- 24 | 25 | .. image:: /images/ginger.jpg 26 | :alt: 'a child cooking' 27 | :align: right 28 | :width: 379 29 | 30 | 31 | Consider an encyclopaedia article about an ingredient, say ginger. 32 | 33 | When you look up *ginger* in a reference work, what you want is *information* about the ingredient - information describing its provenance, its behaviour, its chemical constituents, how it can be cooked. 34 | 35 | You expect that whatever ingredient you look up, the information will be presented in a similar way. And you expect to be informed of 36 | basic facts, such as *ginger is a member of the family that includes turmeric and cardamom*. 37 | 38 | This is also where you'd expect to be alerted about potential problems, such as: *ginger is known to provoke heartburn in some 39 | individuals* or: *ginger may interfere with the effects of anticoagulants, such as warfarin or aspirin*. 40 | 41 | 42 | How to write good reference guides 43 | ---------------------------------- 44 | 45 | Structure the documentation around the code 46 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 47 | 48 | **Give reference documentation the same structure as the codebase**, so that the user can navigate both the code and the documentation for it at the same time. This will also help the maintainers see where reference documentation is missing or needs to be updated. 49 | 50 | 51 | Be consistent 52 | ~~~~~~~~~~~~~ 53 | 54 | **In reference guides, structure, tone, format must all be consistent** - as consistent as those of an encyclopaedia or dictionary. 55 | 56 | 57 | Do nothing but describe 58 | ~~~~~~~~~~~~~~~~~~~~~~~~ 59 | 60 | **The only job of technical reference is to describe**, as clearly and completely as possible. Anything else (explanation, discussion, instruction, speculation, opinion) is not only a distraction, but will make it harder to use and maintain. Provide examples to illustrate the description when appropriate. 61 | 62 | Avoid the temptation to use reference material to instruct in how to achieve things, beyond the basic scope of using the software, and don’t allow explanations of concepts or discussions of topics to develop. Instead, link to how-to guides, explanation and introductory tutorials as appropriate. 63 | 64 | 65 | Be accurate 66 | ~~~~~~~~~~~ 67 | 68 | **These descriptions must be accurate and kept up-to-date.** Any discrepancy between the machinery and your description of it will inevitably lead a user astray. 69 | 70 | 71 | Example from Divio's documentation 72 | ---------------------------------- 73 | 74 | Have a look at `an example from our technical reference section `_. 75 | 76 | .. image:: /images/django-reference-example.png 77 | :alt: 'Django reference example' 78 | :align: right 79 | :width: 379 80 | 81 | This is a typical reference guide (in this case, for our Divio CLI). 82 | 83 | Description is all this article does, setting out in a complete and accurate form the functions, commands and options 84 | of the tool. 85 | 86 | It's hardly a friendly or engaging read, but its purpose is to make looking up information about functionality as swift 87 | and distraction-free as possible. 88 | -------------------------------------------------------------------------------- /requirements.txt: -------------------------------------------------------------------------------- 1 | divio-docs-theme==0.0.21 2 | pyenchant 3 | sphinx 4 | sphinx-autobuild 5 | sphinx_rtd_theme 6 | sphinxcontrib-spelling -------------------------------------------------------------------------------- /structure.rst: -------------------------------------------------------------------------------- 1 | .. raw:: html 2 | 3 | 7 | 8 | 9 | About the structure 10 | =================== 11 | 12 | Why isn't this obvious? 13 | ----------------------- 14 | 15 | This structure is clear, and it works, but there is a reason why it's not so obvious, and that is the way the characteristics of each quadrant of the documentation overlap with those of its neighbours in the scheme. 16 | 17 | .. image:: /images/overview.png 18 | :alt: 'overview of the documentation system' 19 | 20 | Each of the quadrants is similar to its two neighbours: 21 | 22 | * *tutorials and how-to guides* are both concerned with **describing practical steps** 23 | * *how-to guides and technical reference* are both **what we need when we are at work, coding** 24 | * *reference guides and explanation* are both concerned with **theoretical knowledge** 25 | * *tutorials and explanation* are both **most useful when we are studying**, rather than actually working 26 | 27 | 28 | The tendency to collapse 29 | ~~~~~~~~~~~~~~~~~~~~~~~~~ 30 | 31 | Given these overlaps, it's not surprising that the different kinds of documentation become confused and mixed in with each other. In fact, there is a natural gravitational pull of these distinct types of documentation to each other, and it is hard to resist. Its effect is to collapse the structure, and that is why so much documentation looks like this: 32 | 33 | .. image:: /images/collapse.png 34 | :alt: 'collapse of the documentation structure' 35 | 36 | 37 | Adoption of the system 38 | ----------------------- 39 | 40 | 41 | Though it's rare to find it clear examples of it used fully, a great deal of documentation recognises, in different ways, each of these four functions. 42 | 43 | Good examples of the scheme in substantial projects include: 44 | 45 | * the `Divio Developer Handbook `_ 46 | * `Django's documentation `_ 47 | * `django CMS's documentation `_ 48 | 49 | It's possible to use the system even in very minimal documentation, for example `CoReport (an open-source COVID-19 reporting 50 | project) `_. Here, applying the system creates a framework for future documentation, helping ensure that 51 | new material will conform. 52 | 53 | Sometimes the documentation is so minimal that not all quadrants are ready to be represented, as in the case of `Getting started 54 | with Java and Spring-boot `_, which includes 55 | only a tutorial, how-to and reference material. 56 | 57 | `But I never wanted to do DevOps! `_ is the written material 58 | that accompanies a popular workshop. The documentation strictly separate the `tutorial 59 | `_, the steps learners are to follow, from the *explanation* 60 | (`Further reading `_). Both belong to the *most useful when we 61 | are studying* side of the system, so it's natural to include them in a workshop. 62 | 63 | In each case though, however minimal or even incomplete, the system is respected and the clear distinction between sections and 64 | their purposes will benefit the author and user right away, and help guide the expansion of the material as it develops in the 65 | future. 66 | 67 | 68 | About the analysis and its application 69 | --------------------------------------- 70 | 71 | The analysis of documentation in this article is based on several years of experience writing and maintaining documentation, and much time spent considering how to improve it. 72 | 73 | It’s also based on sound principles that come from a variety of disciplines. For example, its conception of tutorials has a pedagogical basis; it posits a tutor and a learner, and considers using software to be a craft in which abstract understanding of general principles follows from concrete steps that deal with particulars. 74 | 75 | The system is presented regularly at talks and interactive workshops. The analysis has been applied to numerous projects, including large internal documentation sets, and has repeatedly procured 76 | benefits of usability and maintainability, across a very wide range of technical subject matter. 77 | -------------------------------------------------------------------------------- /tutorials.rst: -------------------------------------------------------------------------------- 1 | .. _tutorials: 2 | 3 | Tutorials 4 | ========= 5 | 6 | Tutorials are *lessons* that take the reader by the hand through a series of steps to complete a project of some kind. They are what your project needs in order to show a beginner that they can achieve something with it. 7 | 8 | They are wholly **learning-oriented**, and specifically, they are oriented towards *learning how* rather than *learning that*. 9 | 10 | **You are the teacher**, and you are **responsible** for what the student will do. Under **your** instruction, the student will execute a series of actions to achieve some **end**. 11 | 12 | The end and the actions are up to you, but deciding what they should be can be hard work. The end has to be *meaningful*, but also *achievable* for a complete beginner. 13 | 14 | The important thing is that having done the tutorial, the learner is in a position to make sense of the rest of the documentation, and the software itself. 15 | 16 | Most software projects have really bad - or non-existent - tutorials. Tutorials are what will turn your learners into users. **A bad or missing tutorial will prevent your project from acquiring new users.** 17 | 18 | Of the sections describing the four kinds of documentation, this is by far the longest - that's because tutorials are the most 19 | misunderstood and most difficult to do well. The best way of teaching is to have a teacher present, interacting with the 20 | student. That's rarely possible, and our written tutorials will be at best a far-from-perfect substitute. That's all the more 21 | reason to pay special attention to them. 22 | 23 | Tutorials need to be useful for the beginner, easy to follow, meaningful and extremely robust, and kept up-to-date. You might 24 | well find that writing and maintaining your tutorials can occupy as much time and energy as the the other three parts put 25 | together. 26 | 27 | 28 | Analogy from cooking 29 | -------------------- 30 | 31 | .. image:: /images/anselmo.jpg 32 | :alt: 'a child cooking' 33 | :align: right 34 | :width: 379 35 | 36 | Consider an analogy of teaching a child to cook. 37 | 38 | *What* you teach the child to cook isn’t really important. What’s important is that the child finds it enjoyable, and gains confidence, and wants to do it again. 39 | 40 | *Through* the things the child does, it will learn important things about cooking. It will learn what it is like to be in the kitchen, to use the utensils, to handle the food. 41 | 42 | 43 | This is because using **software, like cooking, is a matter of craft**. It’s knowledge - but it is *practical* knowledge, not *theoretical* knowledge. 44 | 45 | When we learn a new craft or skill, we always begin learning it by doing. 46 | 47 | 48 | How to write good tutorials 49 | --------------------------- 50 | 51 | Allow the user to learn by doing 52 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 53 | 54 | **In the beginning, we only learn anything by doing** - it’s how we learn to talk, or walk. 55 | 56 | In your software tutorial, your learner needs to *do* things. The different things that they do while following your tutorial need to cover a wide range of tools and operations, building up from the simplest ones at the start to more complex ones. 57 | 58 | 59 | Get the user started 60 | ~~~~~~~~~~~~~~~~~~~~ 61 | 62 | It’s perfectly acceptable if your beginner’s first steps are hand-held baby steps. It’s also perfectly acceptable if what you get the beginner to do is not the way an experienced person would, or even if it’s not the ‘correct’ way - a tutorial for beginners is not the same thing as a manual for best practice. 63 | 64 | The point of a tutorial is to get your learner **started on their journey**, not to get them to a final destination. 65 | 66 | 67 | Make sure that your tutorial works 68 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 69 | 70 | One of your jobs as a tutor is to inspire the beginner’s confidence: in the software, in the tutorial, in the tutor and, of course, in their own ability to achieve what’s being asked of them. 71 | 72 | There are many things that contribute to this. A friendly tone helps, as does consistent use of language, and a logical progression through the material. But the single most important thing is that **what you ask the beginner to do must work**. The learner needs to see that the actions you ask them to take have the effect you say they will have. 73 | 74 | If the learner's actions produce an error or unexpected results, your tutorial has failed - even if it’s not your fault. When your students are there with you, you can rescue them; if they’re reading your documentation on their own you can’t - so you have to prevent that from happening in advance. This is without doubt easier said than done. 75 | 76 | 77 | Ensure the user sees results immediately 78 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 79 | 80 | **Everything the learner does should accomplish something comprehensible, however small.** If your student has to do strange and incomprehensible things for two pages before they even see a result, that’s much too long. The effect of every action should be visible and evident as soon as possible, and the connection to the action should be clear. 81 | 82 | The conclusion of each section of a tutorial, or the tutorial as a whole, must be a meaningful accomplishment. 83 | 84 | 85 | Make your tutorial repeatable 86 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 87 | 88 | **Your tutorial must be reliably repeatable.** This not easy to achieve: people will be coming to it with different operating systems, levels of experience and tools. What’s more, any software or resources they use are quite likely themselves to change in the meantime. 89 | 90 | The tutorial has to work for all of them, every time. 91 | 92 | Tutorials unfortunately need regular and detailed testing to make sure that they still work. 93 | 94 | 95 | Focus on concrete steps, not abstract concepts 96 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 97 | 98 | **Tutorials need to be concrete**, built around specific, particular actions and outcomes. 99 | 100 | The temptation to introduce abstraction is huge; it is after all how most computing derives its power. But all learning proceeds from the particular and concrete to the general and abstract, and asking the learner to appreciate levels of abstraction before they have even had a chance to grasp the concrete is poor teaching. 101 | 102 | 103 | Provide the minimum necessary explanation 104 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 105 | 106 | **Don’t explain anything the learner doesn’t need to know in order to complete the tutorial.** Extended discussion is important - just not in a tutorial. In a tutorial, it is an obstruction and a distraction. Only the bare minimum is appropriate. Instead, link to explanations elsewhere in the documentation. 107 | 108 | 109 | Focus only on the steps the user needs to take 110 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 111 | 112 | **Your tutorial needs to be focused on the task in hand.** Maybe the command you’re introducing has many other options, or maybe there are different ways to access a certain API. It doesn’t matter: right now, your learner does not need to know about those in order to make progress. 113 | 114 | 115 | Example from Divio's documentation 116 | ---------------------------------- 117 | 118 | Have a look at `our tutorials `_. 119 | 120 | .. image:: /images/django-tutorial-example.png 121 | :alt: 'Django tutorial example' 122 | :align: right 123 | :width: 379 124 | 125 | In particular, see the tutorial for Django. The promise that the tutorial makes is: if you have the basic knowledge 126 | required to follow this tutorial, and you follow its directions, you will end up with with a working Django web 127 | application, complete with Postgres database, S3 media storage, and so on. In order to work as a tutorial, it has to 128 | fulfil that promise. 129 | 130 | Note that it doesn’t tell you what you will *learn*, just what you will *do*. The learning comes out of that doing. The 131 | tutorial takes full responsibility for what you will do and the order in which you will do it. 132 | --------------------------------------------------------------------------------