├── .github └── workflows │ ├── build.yml │ ├── lint.yml │ └── release.yml ├── .gitignore ├── CODE_OF_CONDUCT.md ├── CONTRIBUTING.md ├── README.md └── docs ├── 404.rst ├── Makefile ├── _static ├── .gitkeep └── css │ └── custom.css ├── 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 /.github/workflows/build.yml: -------------------------------------------------------------------------------- 1 | name: Build 2 | 3 | on: push 4 | 5 | jobs: 6 | build: 7 | name: Build documentation 8 | runs-on: ubuntu-latest 9 | 10 | steps: 11 | - name: Checkout Code 12 | uses: actions/checkout@v2 13 | 14 | - name: Set up Python 15 | uses: actions/setup-python@v2 16 | with: 17 | python-version: 3.11 18 | 19 | - name: Install Dependencies 20 | run: | 21 | python -m pip install --upgrade pip 22 | pip install -r docs/requirements.txt 23 | 24 | - name: Build Docs 25 | run: sphinx-build -b html docs docs/_build/html 26 | -------------------------------------------------------------------------------- /.github/workflows/lint.yml: -------------------------------------------------------------------------------- 1 | name: Lint 2 | 3 | on: push 4 | 5 | jobs: 6 | lint: 7 | name: Lint documentation 8 | runs-on: ubuntu-latest 9 | 10 | steps: 11 | - name: Checkout Code 12 | uses: actions/checkout@v2 13 | 14 | - name: Set up Python 15 | uses: actions/setup-python@v2 16 | with: 17 | python-version: 3.11 18 | 19 | - name: Install Dependencies 20 | run: | 21 | python -m pip install --upgrade pip 22 | pip install black flake8 23 | 24 | - name: Run Black 25 | run: black . --check --diff 26 | 27 | - name: Run Flake8 28 | run: flake8 29 | -------------------------------------------------------------------------------- /.github/workflows/release.yml: -------------------------------------------------------------------------------- 1 | name: Release 2 | 3 | on: 4 | push: 5 | branches: 6 | - master 7 | 8 | jobs: 9 | deploy: 10 | name: Build and Deploy Documentation 11 | runs-on: ubuntu-latest 12 | 13 | steps: 14 | - name: Checkout Code 15 | uses: actions/checkout@v2 16 | 17 | - name: Set up Python 18 | uses: actions/setup-python@v2 19 | with: 20 | python-version: 3.11 21 | 22 | - name: Install Dependencies 23 | run: | 24 | python -m pip install --upgrade pip 25 | pip install -r docs/requirements.txt 26 | 27 | - name: Build Documentation 28 | run: sphinx-build -b html docs docs/_build/html 29 | 30 | - name: Deploy to GitHub Pages 31 | uses: peaceiris/actions-gh-pages@v3 32 | with: 33 | github_token: ${{ secrets.GITHUB_TOKEN }} 34 | publish_dir: ./docs/_build/html 35 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | /*env*/ 2 | _build 3 | __pycache__ 4 | _templates/ 5 | *.pyc 6 | *.egg-info/ 7 | .DS_Store 8 | 9 | .vscode/ 10 | .idea/ 11 | -------------------------------------------------------------------------------- /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Code of Conduct 2 | 3 | Your code and ideas behind it will be carefully reviewed, often resulting 4 | in critique and criticism. The review will almost always require 5 | improvements to the code before it can be included in the project. 6 | Know that this happens because everyone involved wants to see the best 7 | possible solution for the overall success of the project. We do not 8 | want to do anything to cause the quality of submission and eventual 9 | result to ever decrease. 10 | 11 | If however, anyone feels personally abused, threatened, or otherwise 12 | uncomfortable due to this process, that is not acceptable. If so, 13 | please contact the individual members, and they will work to resolve 14 | the issue to the best of their ability. 15 | 16 | As a reviewer of code, please strive to keep things civil and focused on 17 | the technical issues involved. We are all humans, and frustrations can 18 | be high on both sides of the process. Try to keep in mind the immortal 19 | words of Bill and Ted, "Be excellent to each other." 20 | 21 | This is based on the Linux kernel "Code of Conduct", 22 | . 23 | 24 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing 2 | 3 | Here's help on how to make contributions, divided into the following sections: 4 | 5 | - general information, 6 | - pull requests and different branches recommended 7 | - no trailing whitespace 8 | 9 | ## General information 10 | 11 | For specific proposals, please provide them as 12 | [pull requests](https://github.com/divio/documentation-framework/pulls) 13 | or 14 | [issues](https://github.com/divio/documentation-framework/issues) 15 | 16 | You are welcome aboard! 17 | 18 | See [CODE OF CONDUCT](./CODE_OF_CONDUCT.md) for our code of conduct; 19 | in short, "Be excellent to each other". 20 | 21 | ## Pull requests and different branches recommended 22 | 23 | Pull requests are preferred, since they are specific. 24 | For more about how to create a pull request, see 25 | . 26 | 27 | We recommend creating different branches for different (logical) 28 | changes, and creating a pull request when you're done into the master branch. 29 | See the GitHub documentation on 30 | [creating branches](https://help.github.com/articles/creating-and-deleting-branches-within-your-repository/) 31 | and 32 | [using pull requests](https://help.github.com/articles/using-pull-requests/). 33 | 34 | ### No trailing whitespace 35 | 36 | Please do not use or include trailing whitespace 37 | (spaces or tabs at the end of a line). 38 | Since they are often not visible, they can cause silent problems 39 | and misleading unexpected changes. 40 | For example, some editors (e.g., Atom) quietly delete them by default. 41 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # The Documentation System 2 | 3 | A comprehensive and practical system that can help maintainers of product documentation. 4 | 5 | Published at https://documentation.divio.com 6 | 7 | Author: Daniele Procida 8 | -------------------------------------------------------------------------------- /docs/404.rst: -------------------------------------------------------------------------------- 1 | :hide-toc: 2 | :orphan: 3 | 4 | 404 page not found 5 | ================== 6 | 7 | Sorry, that page cannot be found. 8 | 9 | .. raw:: html 10 | 11 |

Back to overview

13 | 14 | Or, try a text search for the information you need. 15 | -------------------------------------------------------------------------------- /docs/Makefile: -------------------------------------------------------------------------------- 1 | # Minimal makefile for Sphinx documentation 2 | # 3 | 4 | # You can set these variables from the command line, and also 5 | # from the environment for the first two. 6 | SPHINXOPTS ?= 7 | SPHINXBUILD ?= sphinx-build 8 | SOURCEDIR = . 9 | BUILDDIR = _build 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 | .PHONY: help Makefile 16 | 17 | # Catch-all target: route all unknown targets to Sphinx using the new 18 | # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). 19 | %: Makefile 20 | @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 21 | -------------------------------------------------------------------------------- /docs/_static/.gitkeep: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /docs/_static/css/custom.css: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /docs/adoption.rst: -------------------------------------------------------------------------------- 1 | .. meta:: 2 | :description: 3 | Find details on who uses the documentation system, inc Divio. This is an incomplete list of projects, products 4 | and organisations who have adopted this sytem. 5 | 6 | .. _adoption: 7 | 8 | Who is using the system? 9 | ======================== 10 | 11 | .. sidebar:: Not listed here? 12 | 13 | If you're using the system, or are in the process of adopting it, please let us know if you'd like to be 14 | listed here. 15 | 16 | This is an incomplete list of projects, products and organisations that have adopted the system in their own 17 | bodies of documentation. In some cases the adoption remains partial or is still a work in progress. 18 | 19 | * `BrachioGraph `_, the cheapest, simplest pen-plotter 20 | * `BeeWare `_, the write-once-deploy-anywhere project, for `Toga `_, 21 | `Briefcase `_, `Rubicon `_ and `Rubicon Java 22 | `_. 23 | * Bosch (internal) 24 | * `Ciw `_, the discrete event simulation library 25 | * `Cloudflare Workers docs `_ (related article, `New and 26 | improved Workers Docs `_) 27 | * `Divio `_ 28 | * `Django `_ 29 | * `django CMS `_ 30 | * `edo `_, a library for Evolutionary Dataset Optimisation 31 | * Ericsson (internal) 32 | * `Gensim `_, `How to Author Gensim Documentation 33 | `_ 34 | * `Snowpack `_, a frontend build tool, designed for the modern web 35 | * `StrongLoop/LoopBack `_ by IBM 36 | * `Lisk `_ 37 | * `NashPy `_, a Python mathematical library for computing Nash equilibria 38 | * `nbchkr `_, a system for assessing students' assignments in Jupyter Notebooks 39 | * `NumPy `_, the scientific Python library (related article, `Documentation as a way to 40 | build Community `_) 41 | * `PDFminer.six `_ 42 | * `PostgREST `_ 43 | * `PIconnect `_ 44 | * Tesla Motors (internal) 45 | * `WebAccess/DMP `_ 46 | * `Wechaty `_ 47 | * Zalando (internal) 48 | * `Attune `_ Automation 49 | 50 | 51 | Other mentions and references of interest 52 | ----------------------------------------- 53 | 54 | * `Django Axes proposal `_ 55 | * `Julia language proposal `_ 56 | * `Why You Should Document Your Work As a Data Scientist `_ 57 | * `Koninklijke Bibliotheek (National Library of the Netherlands) research software lab 58 | `_ 59 | * `Tutorials in Jenkins user documentation 60 | `_ 61 | -------------------------------------------------------------------------------- /docs/conf.py: -------------------------------------------------------------------------------- 1 | # Configuration file for the Sphinx documentation builder. 2 | # 3 | # Full list of options can be found in the Sphinx documentation: 4 | # https://www.sphinx-doc.org/en/master/usage/configuration.html 5 | 6 | # 7 | # -- sys.path preparation ---------------------------------------------------- 8 | # 9 | 10 | import os 11 | import sys 12 | import datetime 13 | 14 | sys.path.insert(0, os.path.abspath(".")) 15 | 16 | 17 | # 18 | # -- Project information ------------------------------------------------------ 19 | # 20 | 21 | # Add any paths that contain templates here, relative to this directory. 22 | # templates_path = ['_templates'] 23 | 24 | project = "Documentation System" 25 | full_title = project 26 | copyright = f"{datetime.date.today().year} Divio Technologies AB" 27 | author = "Divio" 28 | version = "1.0" 29 | release = version 30 | 31 | # 32 | # -- General configuration ---------------------------------------------------- 33 | # 34 | 35 | extensions = [] 36 | 37 | # 38 | # -- Options for the theme ---------------------------------------------------- 39 | # 40 | 41 | html_theme = "furo" 42 | html_theme_options = { 43 | "show_cloud_banner": True, 44 | "cloud_banner_markup": """ 45 |
46 | Cloud deployment by Divio 47 | 50 |

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

52 | Find out more at Divio 54 |
55 | """, 56 | "analytics_id": "G-WT28ECPSX4", 57 | "style_external_links": True, 58 | "navigation_depth": 2, 59 | "sidebar_hide_name": True, 60 | } 61 | 62 | # 63 | # -- Options for HTML output -------------------------------------------------- 64 | # 65 | 66 | html_title = full_title 67 | html_help_basename = "DivioDocumentationSystem" 68 | html_static_path = ["_static"] 69 | html_css_files = [ 70 | "css/custom.css", 71 | "styles/furo.css", 72 | ] 73 | 74 | # 75 | # -- Options for Sphinx ------------------------------------------------------- 76 | # 77 | 78 | source_suffix = ".rst" 79 | master_doc = "index" 80 | language = None 81 | exclude_patterns = ["README.rst", "_build", "Thumbs.db", ".DS_Store", "env"] 82 | on_rtd = os.environ.get("READTHEDOCS", None) == "True" 83 | 84 | # 85 | # -- Options for latex output ------------------------------------------------- 86 | # 87 | 88 | latex_documents = [ 89 | (master_doc, html_help_basename + ".tex", full_title, author, "manual"), 90 | ] 91 | 92 | # 93 | # -- Options for manual page output ------------------------------------------- 94 | # 95 | 96 | man_pages = [(master_doc, html_help_basename, full_title, [author], 1)] 97 | -------------------------------------------------------------------------------- /docs/explanation.rst: -------------------------------------------------------------------------------- 1 | .. meta:: 2 | :description: 3 | Find details on how Divio formats explanations in our documentation. Explanation, or discussions, clarify and 4 | illuminate a particular topic. Learn more here. 5 | 6 | .. _explanation: 7 | 8 | Explanation 9 | ================= 10 | 11 | 12 | Explanation, or discussions, *clarify and illuminate a particular topic*. They broaden the documentation’s coverage of a topic. 13 | 14 | They are **understanding-oriented**. 15 | 16 | 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. 17 | 18 | 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. 19 | 20 | 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. 21 | 22 | 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. 23 | 24 | Analogy from cooking 25 | -------------------- 26 | 27 | .. image:: /images/mcgee.jpg 28 | :alt: 'a child cooking' 29 | :align: right 30 | :width: 379 31 | 32 | Think about a work that discusses food and cooking in the context of history, science and technology. It's *about* 33 | cooking and the kitchen. 34 | 35 | It doesn't teach, it's not a collection of recipes, and it doesn't just describe. 36 | 37 | Instead, it analyses, considers things from multiple perspectives. It might explain why it is we now do things the way we do, or 38 | even describe bad ways of doing things, or obscure alternatives. 39 | 40 | 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. 41 | 42 | It's something we might read at our leisure, away from the kitchen itself, when we want 43 | to think about cooking at a higher level, and to understand more about the subject. 44 | 45 | 46 | How to write a good explanation 47 | ---------------------------------- 48 | 49 | Provide context 50 | ~~~~~~~~~~~~~~~ 51 | 52 | **Explanations are the place for background and context** - for example, *Web forms and how they are handled in Django*, or *Search in django CMS*. 53 | 54 | They can also explain *why* things are so - design decisions, historical reasons, technical constraints. 55 | 56 | 57 | Discuss alternatives and opinions 58 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 59 | 60 | **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. 61 | 62 | Discussions can even consider and weigh up contrary *opinions* - for example, whether test modules should be in a package directory, or not. 63 | 64 | 65 | Don't instruct, or provide technical reference 66 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 67 | 68 | **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. 69 | 70 | 71 | Example from Divio's documentation 72 | ---------------------------------- 73 | 74 | Have a look at `our explanation section `_ (titled "Background information" - 75 | the name is not important as long as the purpose is clear). 76 | 77 | .. image:: /images/divio-explanation-example.png 78 | :alt: 'Django explanation example' 79 | :align: right 80 | :width: 379 81 | 82 | These articles don’t teach anything. They don’t tell the user what to do. They aren’t reference guides. They just 83 | discuss particular topics. The user doesn’t *need* to know about (for example) caching or CDN or how we manage 84 | environment variables in order to use the platform or achieve any particular task, but the time is likely to come when 85 | someone's experience and use of the platform will be improved by having a clearer, better, deeper understanding of 86 | those things. 87 | 88 | These articles provide the bigger picture, the context. Users are human beings; maybe they don’t strictly need to know 89 | why we do a certain thing a certain way, but knowing it might well provide them with a kind of satisfaction and comfort 90 | that makes them a happier user of the product. 91 | -------------------------------------------------------------------------------- /docs/how-to-guides.rst: -------------------------------------------------------------------------------- 1 | .. meta:: 2 | :description: 3 | Find details on how Divio formats how-to guides in our documentation. How-to guides take the reader through the 4 | steps required to solve a real-world problem. 5 | 6 | .. _how-to: 7 | 8 | How-to guides 9 | ============= 10 | 11 | How-to guides take the reader through the steps required to solve a real-world problem. 12 | 13 | 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*. 14 | 15 | They are wholly **goal-oriented**. 16 | 17 | **How-to guides are wholly distinct from tutorials** and must not be confused with them: 18 | 19 | * A tutorial is what you decide a beginner needs to know. 20 | * A how-to guide is an answer to a question that only a user with some experience could even formulate. 21 | 22 | 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. 23 | 24 | Unlike tutorials, how-to guides in software documentation tend to be done fairly well. They’re also fun and easy to write. 25 | 26 | 27 | Analogy from cooking 28 | -------------------- 29 | 30 | .. image:: /images/recipe.jpg 31 | :alt: 'a recipe' 32 | 33 | 34 | Think about a recipe, for preparing something to eat. 35 | 36 | 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. 37 | 38 | 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, 39 | or contains irrelevant discussion of the ingredients. 40 | 41 | 42 | How to write good how-to guides 43 | ------------------------------- 44 | 45 | Provide a series of steps 46 | ~~~~~~~~~~~~~~~~~~~~~~~~~ 47 | 48 | **How-to guides must contain a list of steps, that need to be followed in order** (just like tutorials do). 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. 49 | 50 | 51 | Focus on results 52 | ~~~~~~~~~~~~~~~~~~~~ 53 | 54 | **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. 55 | 56 | 57 | Solve a particular problem 58 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ 59 | 60 | **A how-to guide must address a specific question or problem**: *How do I …?* 61 | 62 | 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. 63 | 64 | 65 | Don't explain concepts 66 | ~~~~~~~~~~~~~~~~~~~~~~~ 67 | 68 | **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. 69 | 70 | 71 | Allow for some flexibility 72 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ 73 | 74 | **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. 75 | 76 | 77 | Leave things out 78 | ~~~~~~~~~~~~~~~~ 79 | 80 | **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. 81 | 82 | 83 | Name guides well 84 | ~~~~~~~~~~~~~~~~ 85 | 86 | **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. 87 | 88 | 89 | Example from Divio's documentation 90 | ---------------------------------- 91 | 92 | Have a look at `our how-to guides `_. 93 | 94 | .. image:: /images/django-how-to-example.png 95 | :alt: 'Django how-to example' 96 | :align: right 97 | :width: 379 98 | 99 | Each one of these is an answer to a question, or problem: *how do I...?* Each title can clearly be preceded by the 100 | words “How to”. Each one is a recipe, that takes you through the steps required to complete a specific task. 101 | 102 | Although both the tutorials and the how-to guides serve the needs of the user, the tutorials are led by the author who 103 | knows what the user needs to know, while the how-to guides are led by the user who asks the questions. 104 | -------------------------------------------------------------------------------- /docs/images/anselmo.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/divio/documentation-framework/HEAD/docs/images/anselmo.jpg -------------------------------------------------------------------------------- /docs/images/collapse.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/divio/documentation-framework/HEAD/docs/images/collapse.png -------------------------------------------------------------------------------- /docs/images/divio-explanation-example.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/divio/documentation-framework/HEAD/docs/images/divio-explanation-example.png -------------------------------------------------------------------------------- /docs/images/django-how-to-example.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/divio/documentation-framework/HEAD/docs/images/django-how-to-example.png -------------------------------------------------------------------------------- /docs/images/django-reference-example.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/divio/documentation-framework/HEAD/docs/images/django-reference-example.png -------------------------------------------------------------------------------- /docs/images/django-tutorial-example.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/divio/documentation-framework/HEAD/docs/images/django-tutorial-example.png -------------------------------------------------------------------------------- /docs/images/ginger.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/divio/documentation-framework/HEAD/docs/images/ginger.jpg -------------------------------------------------------------------------------- /docs/images/mcgee.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/divio/documentation-framework/HEAD/docs/images/mcgee.jpg -------------------------------------------------------------------------------- /docs/images/overview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/divio/documentation-framework/HEAD/docs/images/overview.png -------------------------------------------------------------------------------- /docs/images/recipe.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/divio/documentation-framework/HEAD/docs/images/recipe.jpg -------------------------------------------------------------------------------- /docs/index.rst: -------------------------------------------------------------------------------- 1 | .. meta:: 2 | :description: 3 | Find the software documentation system for Divio. Includes comprehensive tutorials, how-to guides, technical 4 | reference and explanation. Learn more here. 5 | 6 | .. raw:: html 7 | 8 | 12 | 13 | 14 | The Documentation System 15 | ======================== 16 | 17 | .. rst-class:: quote 18 | 19 | The Grand Unified Theory of Documentation 20 | 21 | .. rst-class:: attribution 22 | 23 | \- David Laing 24 | 25 | 26 | There is a secret that needs to be understood in order to write good software documentation: there isn’t one 27 | thing called *documentation*, there are four. 28 | 29 | They are: *tutorials*, *how-to guides*, *technical reference* and *explanation*. They represent four different 30 | purposes or functions, and require four different approaches to their creation. Understanding the implications of 31 | this will help improve most documentation - often immensely. 32 | 33 | 34 | About the system 35 | ---------------- 36 | 37 | .. image:: /images/overview.png 38 | :alt: 'overview of the documentation system' 39 | 40 | 41 | The documentation system outlined here is a simple, comprehensive and nearly universally-applicable scheme. It 42 | is proven in practice across a wide variety of fields and applications. 43 | 44 | There are some very simple principles that govern documentation that are very rarely if ever spelled out. They seem 45 | to be a secret, though they shouldn’t be. 46 | 47 | If you can put these principles into practice, **it will make your documentation better and your project, product 48 | or team more successful** - that’s a promise. 49 | 50 | :ref:`The system is widely adopted ` for large and small, open and proprietary documentation projects. 51 | 52 | 53 | .. toctree:: 54 | :maxdepth: 0 55 | 56 | introduction 57 | tutorials 58 | how-to-guides 59 | reference 60 | explanation 61 | structure 62 | adoption 63 | 64 | 65 | Video presentation 66 | ------------------ 67 | 68 | If you'd prefer to watch a video covering this topic, here is it (courtesy of PyCon Australia 2017). 69 | 70 | .. raw:: html 71 | 72 | 73 | -------------------------------------------------------------------------------- /docs/introduction.rst: -------------------------------------------------------------------------------- 1 | .. meta:: 2 | :description: 3 | Find an introduction to how Divio formats and uses documentation. Our approach is to make documentation work for 4 | everyone. Learn why this is important here. 5 | 6 | .. raw:: html 7 | 8 | 12 | 13 | 14 | Introduction 15 | ============ 16 | 17 | The problem and the solution 18 | ------------------------------ 19 | 20 | The problem it solves 21 | ~~~~~~~~~~~~~~~~~~~~~ 22 | 23 | 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 24 | you’d like them to. 25 | 26 | Nearly everyone understands this. Nearly everyone knows that they need good documentation, and **most people try to create good documentation**. And **most people fail**. 27 | 28 | Usually, it’s not because they don’t try hard enough. Usually, it’s because they are not doing it the right way. 29 | 30 | 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. 31 | 32 | 33 | The 'secret' 34 | ~~~~~~~~~~~~ 35 | 36 | 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. 37 | 38 | And documentation needs to be explicitly structured around them, and they all must be kept separate and distinct from each other. 39 | 40 | .. list-table:: 41 | :widths: 16 21 21 21 21 42 | :header-rows: 1 43 | 44 | * - \ 45 | - :ref:`Tutorials ` 46 | - :ref:`How-to guides ` 47 | - :ref:`Reference ` 48 | - :ref:`Explanation ` 49 | * - *oriented to* 50 | - learning 51 | - a goal 52 | - information 53 | - understanding 54 | * - *must* 55 | - allow the newcomer to get started 56 | - show how to solve a specific problem 57 | - describe the machinery 58 | - explain 59 | * - *its form* 60 | - a lesson 61 | - a series of steps 62 | - dry description 63 | - discursive explanation 64 | * - *analogy* 65 | - teaching a small child how to cook 66 | - a recipe in a cookery book 67 | - a reference encyclopedia article 68 | - an article on culinary social history 69 | 70 | This division makes it obvious to both author and reader what material, and what *kind* of material, goes where. It tells the 71 | author **how to write**, and **what to write**, and **where to write it**. It saves the author from wasting a great deal of time 72 | trying to wrestle the information they want to impart into a shape that makes sense, because **each of these kinds of 73 | documentation has only one job**. 74 | 75 | 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. 76 | 77 | 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. 78 | 79 | In the following sections, each of these four parts is dealt with in detail. 80 | 81 | 82 | Making documentation work 83 | ------------------------- 84 | 85 | For authors 86 | ~~~~~~~~~~~ 87 | 88 | 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. 89 | 90 | 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. 91 | 92 | 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. 93 | 94 | 95 | For readers 96 | ~~~~~~~~~~~ 97 | 98 | 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. 99 | 100 | 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. 101 | -------------------------------------------------------------------------------- /docs/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=source 11 | set BUILDDIR=_build 12 | 13 | %SPHINXBUILD% >NUL 2>NUL 14 | if errorlevel 9009 ( 15 | echo. 16 | echo.The 'sphinx-build' command was not found. Make sure you have Sphinx 17 | echo.installed, then set the SPHINXBUILD environment variable to point 18 | echo.to the full path of the 'sphinx-build' executable. Alternatively you 19 | echo.may add the Sphinx directory to PATH. 20 | echo. 21 | echo.If you don't have Sphinx installed, grab it from 22 | echo.https://www.sphinx-doc.org/ 23 | exit /b 1 24 | ) 25 | 26 | if "%1" == "" goto help 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 | -------------------------------------------------------------------------------- /docs/reference.rst: -------------------------------------------------------------------------------- 1 | .. meta:: 2 | :description: 3 | Find details on how Divio formats reference guides in our documentation. Reference guides are technical 4 | descriptions of the machinery and how to operate it. 5 | 6 | .. _reference: 7 | 8 | Reference guides 9 | ================= 10 | 11 | Reference guides are *technical descriptions of the machinery* and how to operate it. 12 | 13 | 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. 14 | 15 | Reference material is **information-oriented**. 16 | 17 | 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. 18 | 19 | Reference material should be **simple and to the point**. 20 | 21 | 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). 22 | 23 | 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. 24 | 25 | Reference material tends to be written well. It can even - to some extent - be generated automatically, but this is never sufficient on its own. 26 | 27 | Analogy from cooking 28 | -------------------- 29 | 30 | .. image:: /images/ginger.jpg 31 | :alt: 'a child cooking' 32 | :align: right 33 | :width: 379 34 | 35 | 36 | Consider an encyclopedia article about an ingredient, say ginger. 37 | 38 | 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. 39 | 40 | You expect that whatever ingredient you look up, the information will be presented in a similar way. And you expect to be informed of 41 | basic facts, such as *ginger is a member of the family that includes turmeric and cardamom*. 42 | 43 | This is also where you'd expect to be alerted about potential problems, such as: *ginger is known to provoke heartburn in some 44 | individuals* or: *ginger may interfere with the effects of anticoagulants, such as warfarin or aspirin*. 45 | 46 | 47 | How to write good reference guides 48 | ---------------------------------- 49 | 50 | Structure the documentation around the code 51 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 52 | 53 | **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. 54 | 55 | 56 | Be consistent 57 | ~~~~~~~~~~~~~ 58 | 59 | **In reference guides, structure, tone, format must all be consistent** - as consistent as those of an encyclopaedia or dictionary. 60 | 61 | 62 | Do nothing but describe 63 | ~~~~~~~~~~~~~~~~~~~~~~~~ 64 | 65 | **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. 66 | 67 | 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. 68 | 69 | 70 | Be accurate 71 | ~~~~~~~~~~~ 72 | 73 | **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. 74 | 75 | 76 | Example from Divio's documentation 77 | ---------------------------------- 78 | 79 | Have a look at `an example from our technical reference section `_. 80 | 81 | .. image:: /images/django-reference-example.png 82 | :alt: 'Django reference example' 83 | :align: right 84 | :width: 379 85 | 86 | This is a typical reference guide (in this case, for our Divio CLI). 87 | 88 | Description is all this article does, setting out in a complete and accurate form the functions, commands and options 89 | of the tool. 90 | 91 | It's hardly a friendly or engaging read, but its purpose is to make looking up information about functionality as swift 92 | and distraction-free as possible. 93 | -------------------------------------------------------------------------------- /docs/requirements.txt: -------------------------------------------------------------------------------- 1 | click 2 | divio-cli 3 | https://github.com/divio/docs-theme/archive/master.zip#egg=furo 4 | Sphinx 5 | sphinx-autobuild 6 | sphinxcontrib-spelling 7 | sphinxcontrib-mermaid 8 | sphinx-notfound-page 9 | sphinx-click 10 | sphinx-inline-tabs 11 | sphinx-rtd-theme 12 | pyenchant 13 | docutils<=0.17 14 | -------------------------------------------------------------------------------- /docs/structure.rst: -------------------------------------------------------------------------------- 1 | .. meta:: 2 | :description: 3 | Find details on how Divio formats the structure in our documentation. This goes into why different documentation 4 | can overlap, and end up causing confusion. 5 | 6 | .. raw:: html 7 | 8 | 12 | 13 | 14 | About the structure 15 | =================== 16 | 17 | Why isn't this obvious? 18 | ----------------------- 19 | 20 | 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. 21 | 22 | .. image:: /images/overview.png 23 | :alt: 'overview of the documentation system' 24 | 25 | Each of the quadrants is similar to its two neighbours: 26 | 27 | * *tutorials and how-to guides* are both concerned with **describing practical steps** 28 | * *how-to guides and technical reference* are both **what we need when we are at work, coding** 29 | * *reference guides and explanation* are both concerned with **theoretical knowledge** 30 | * *tutorials and explanation* are both **most useful when we are studying**, rather than actually working 31 | 32 | 33 | The tendency to collapse 34 | ~~~~~~~~~~~~~~~~~~~~~~~~~ 35 | 36 | 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: 37 | 38 | .. image:: /images/collapse.png 39 | :alt: 'collapse of the documentation structure' 40 | 41 | 42 | Adoption of the system 43 | ----------------------- 44 | 45 | 46 | Though it's rare to find clear examples of it used fully, a great deal of documentation recognises, in different ways, each of these four functions. 47 | 48 | Good examples of the scheme in substantial projects include: 49 | 50 | * the `Divio Developer Handbook `_ 51 | * `Django's documentation `_ 52 | * `django CMS's documentation `_ 53 | 54 | Sometimes the documentation is so minimal that not all quadrants are ready to be represented, as in the case of `Getting started 55 | with Java and Spring-boot `_, which includes 56 | only a tutorial, how-to and reference material. 57 | 58 | In each case though, however minimal or even incomplete, the system is respected and the clear distinction between sections and 59 | their purposes will benefit the author and user right away, and help guide the expansion of the material as it develops in the 60 | future. 61 | 62 | 63 | About the analysis and its application 64 | --------------------------------------- 65 | 66 | 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. 67 | 68 | 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. 69 | 70 | 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 71 | benefits of usability and maintainability, across a very wide range of technical subject matter. 72 | -------------------------------------------------------------------------------- /docs/tutorials.rst: -------------------------------------------------------------------------------- 1 | .. meta:: 2 | :description: 3 | Find details on how Divio formats tutorial guides in our documentation. These are lessons that take the reader 4 | by the hand through a series of steps. Learn more here. 5 | 6 | .. _tutorials: 7 | 8 | Tutorials 9 | ========= 10 | 11 | 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. 12 | 13 | They are wholly **learning-oriented**, and specifically, they are oriented towards *learning how* rather than *learning that*. 14 | 15 | **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**. 16 | 17 | 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. 18 | 19 | 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. 20 | 21 | 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.** 22 | 23 | Of the sections describing the four kinds of documentation, this is by far the longest - that's because tutorials are the most 24 | misunderstood and most difficult to do well. The best way of teaching is to have a teacher present, interacting with the 25 | student. That's rarely possible, and our written tutorials will be at best a far-from-perfect substitute. That's all the more 26 | reason to pay special attention to them. 27 | 28 | Tutorials need to be useful for the beginner, easy to follow, meaningful and extremely robust, and kept up-to-date. You might 29 | well find that writing and maintaining your tutorials can occupy as much time and energy as the other three parts put 30 | together. 31 | 32 | 33 | Analogy from cooking 34 | -------------------- 35 | 36 | .. image:: /images/anselmo.jpg 37 | :alt: 'a child cooking' 38 | :align: right 39 | :width: 379 40 | 41 | Consider an analogy of teaching a child to cook. 42 | 43 | *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. 44 | 45 | *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. 46 | 47 | 48 | This is because using **software, like cooking, is a matter of craft**. It’s knowledge - but it is *practical* knowledge, not *theoretical* knowledge. 49 | 50 | When we learn a new craft or skill, we always begin learning it by doing. 51 | 52 | 53 | How to write good tutorials 54 | --------------------------- 55 | 56 | Allow the user to learn by doing 57 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 58 | 59 | **In the beginning, we only learn anything by doing** - it’s how we learn to talk, or walk. 60 | 61 | 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. 62 | 63 | 64 | Get the user started 65 | ~~~~~~~~~~~~~~~~~~~~ 66 | 67 | 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. 68 | 69 | The point of a tutorial is to get your learner **started on their journey**, not to get them to a final destination. 70 | 71 | 72 | Make sure that your tutorial works 73 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 74 | 75 | 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. 76 | 77 | 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. 78 | 79 | 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. 80 | 81 | 82 | Ensure the user sees results immediately 83 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 84 | 85 | **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. 86 | 87 | The conclusion of each section of a tutorial, or the tutorial as a whole, must be a meaningful accomplishment. 88 | 89 | 90 | Make your tutorial repeatable 91 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 92 | 93 | **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. 94 | 95 | The tutorial has to work for all of them, every time. 96 | 97 | Tutorials unfortunately need regular and detailed testing to make sure that they still work. 98 | 99 | 100 | Focus on concrete steps, not abstract concepts 101 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 102 | 103 | **Tutorials need to be concrete**, built around specific, particular actions and outcomes. 104 | 105 | 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. 106 | 107 | 108 | Provide the minimum necessary explanation 109 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 110 | 111 | **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. 112 | 113 | 114 | Focus only on the steps the user needs to take 115 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 116 | 117 | **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. 118 | 119 | 120 | Example from Divio's documentation 121 | ---------------------------------- 122 | 123 | Have a look at `our tutorials `_. 124 | 125 | .. image:: /images/django-tutorial-example.png 126 | :alt: 'Django tutorial example' 127 | :align: right 128 | :width: 379 129 | 130 | In particular, see the tutorial for Django. The promise that the tutorial makes is: if you have the basic knowledge 131 | required to follow this tutorial, and you follow its directions, you will end up with with a working Django web 132 | application, complete with Postgres database, S3 media storage, and so on. In order to work as a tutorial, it has to 133 | fulfil that promise. 134 | 135 | Note that it doesn’t tell you what you will *learn*, just what you will *do*. The learning comes out of that doing. The 136 | tutorial takes full responsibility for what you will do and the order in which you will do it. 137 | --------------------------------------------------------------------------------