First commit

.gitignore

@@ -0,0 +1,6 @@
+/*env*/
+_build
+.DS_Store
+__pycache__
+.idea/
+_templates/

Makefile

@@ -0,0 +1,54 @@
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = DocumentationSystem
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+VENV = env/bin/activate
+PORT = 8090
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+install:
+	@echo "... setting up virtualenv"
+	python3 -m venv env
+	. $(VENV); pip install --upgrade -r requirements.txt
+	@echo "\n" \
+	  "--------------------------------------------------------------- \n" \
+      "* watch, build and serve the documentation: make run \n" \
+	  "* check spelling: make spelling \n" \
+	  "\n" \
+      "enchant must be installed in order for pyenchant (and therefore \n" \
+	  "spelling checks) to work. \n" \
+	  "--------------------------------------------------------------- \n"
+
+clean:
+	-rm -rf _build/*
+
+run:
+	. $(VENV); sphinx-autobuild $(ALLSPHINXOPTS) --ignore ".git/*" --ignore "*.scss" . -a _build/html --host 0.0.0.0 --port $(PORT)
+
+test:
+	. $(VENV); $(SPHINXBUILD) -b html . _build/html
+
+html:
+	. $(VENV); $(SPHINXBUILD) -b html . _build/html
+
+spelling:
+	. $(VENV); $(SPHINXBUILD) -b spelling $(ALLSPHINXOPTS) . _build/spelling
+	@echo
+	@echo "Check finished. Wrong words can be found in " \
+		"_build/spelling/output.txt."
+
+quickstart:
+	. $(VENV); sphinx-quickstart
+
+.PHONY: help install clean run Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

README.rst

@@ -0,0 +1,4 @@
+The documentation
+=================
+
+A comprehensive and practical system that can help maintainers of product documentation.

conf.py

@@ -0,0 +1,60 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'Documentation system'
+copyright = '2020, Daniele Procida'
+author = 'Daniele Procida'
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+try:
+    import divio_docs_theme
+except ModuleNotFoundError:
+    html_theme = 'alabaster'
+else:
+    html_theme = 'divio_docs_theme'
+    html_theme_path = [divio_docs_theme.get_html_theme_path()]
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+master_doc = 'index'

explanation.rst

@@ -0,0 +1,58 @@
+Explanation
+=================
+
+Explanation, or discussions, *clarify and illuminate a particular topic*. They broaden the documentation’s coverage of a topic.
+
+They are **understanding-oriented**.
+
+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.
+
+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.
+
+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 and have to write down something about it.
+
+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.
+
+Analogy from cooking
+--------------------
+
+.. image:: /images/mcgee.jpg
+   :alt: 'a child cooking'
+   :align: right
+   :width: 379
+
+Think about a work that discusses food and cooking in the context of history, science and technology. It's *about*
+cooking and the kitchen.
+
+It doesn't teach, it's not a collection of recipes, and it doesn't just describe.
+
+Instead , it analyses, considers things from multiple perspectives. It might explain why it is we now do things the way we do, or
+even describe bad ways of doing things, or obscure alternatives.
+
+It's something we might read at our leisure, away from the kitchen itself, when we want to think about cooking at a higher level, and
+to understand more about the subject.
+
+
+How to write good explanation
+----------------------------------
+
+Provide context
+~~~~~~~~~~~~~~~
+
+**Explanations are the place for background and context** - for example, *Web forms and how they are handled in Django*, or *Search in django CMS*.
+
+They can also explain *why* things are so - design decisions, historical reasons, technical constraints.
+
+
+Discuss alternatives and opinions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**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,
+
+Discussions can even consider and weigh up contrary *opinions* - for example, whether test modules should be in a package directory, or not.
+
+
+Don't instruct, or provide technical reference
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+E**xplanation 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 describe. These functions of documentation are already taken care of in other sections.

how-to-guides.rst

@@ -0,0 +1,76 @@
+How-to guides
+=============
+
+How-to guides take the reader through the steps required to solve a real-world problem.
+
+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*.
+
+They are wholly **goal-oriented**.
+
+How-to guides are quite distinct from tutorials. A how-to guide is an answer to a question that a true beginner might not even be able to formulate.
+
+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.
+
+Unlike tutorials, how-to guides in software documentation tend to be done fairly well. They’re also fun and easy to write.
+
+
+Analogy from cooking
+--------------------
+
+.. image:: /images/recipe.jpg
+   :alt: 'a recipe'
+
+
+Think about a recipe, for preparing something to eat.
+
+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.
+
+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,
+or contains irrelevant discussion of the ingredients.
+
+
+How to write good how-to guides
+-------------------------------
+
+Provide a series of steps
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**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.
+
+
+Focus on results
+~~~~~~~~~~~~~~~~~~~~
+
+**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.
+
+
+Solve a particular problem
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**A how-to guide must address a specific question or problem**: *How do I …?*
+
+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.
+
+
+Don't explain concepts
+~~~~~~~~~~~~~~~~~~~~~~~
+
+**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.
+
+
+Allow for some flexibility
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**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.
+
+
+Leave things out
+~~~~~~~~~~~~~~~~
+
+**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.
+
+
+Name guides well
+~~~~~~~~~~~~~~~~
+
+**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.

index.rst

@@ -0,0 +1,48 @@
+The documentation system
+================================================
+
+There is a secret that needs to be understood in order to write good software documentation: there isn’t one
+thing called *documentation*, there are four.
+
+They are: *tutorials*, *how-to guides*, *technical reference* and *explanation*. They represent four different
+purposes or functions, and require four different approaches to their creation. Understanding the implications of
+this will help improve most documentation - often immensely.
+
+
+About the system
+----------------
+
+.. image:: /images/overview.png
+   :alt: 'overview of the documentation system'
+
+
+The documentation system outlined here is a simple, comprehensive and nearly universally-applicable scheme. It
+is proven in practice across a wide variety of fields and applications.
+
+There are some very simple principles that govern documentation that are very rarely if ever spelled out. They seem
+to be a secret, though they shouldn’t be.
+
+If you can put these principles into practice, **it will make your documentation better and your project, product
+or team more successful** - that’s a promise.
+
+
+.. toctree::
+   :maxdepth: 0
+   :hidden:
+
+   introduction
+   tutorials
+   how-to-guides
+   reference
+   explanation
+   structure
+
+
+Video presentation
+------------------
+
+If you'd prefer to watch a video covering this topic, here is it (courtesy of PyCon Australia 2017).
+
+..  raw:: html
+
+    <iframe width="560" height="315" src="https://www.youtube.com/embed/t4vKPhjcMZg" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

introduction.rst

@@ -0,0 +1,79 @@
+.. raw:: html
+
+    <style>
+        table.docutils { width: 100%; table-layout: fixed;}
+        table.docutils th, table.docutils td { white-space: normal }
+    </style>
+
+
+Introduction
+============
+
+The problem and the solution
+------------------------------
+
+The problem it solves
+~~~~~~~~~~~~~~~~~~~~~
+
+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
+you’d like them to.
+
+Nearly everyone understands this. Nearly everyone knows that that they need good documentation, and **most people try to create good documentation**. And **most people fail**.
+
+Usually, it’s not because they don’t try hard enough. Usually, it’s because they are not doing it the right way.
+
+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.
+
+
+The 'secret'
+~~~~~~~~~~~~
+
+It's not really a secret: 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 documentation needs to be explicitly structured around them, and they all must be kept separate and distinct from each other.
+
+.. list-table::
+   :widths: 16 21 21 21 21
+   :header-rows: 1
+
+   * - \
+     - Tutorials
+     - How-to guides
+     - Reference
+     - Explanation
+   * - *oriented to*
+     - learning
+     - a goal
+     - information
+     - understanding
+   * - *must*
+     - allow the newcomer to get started
+     - show how to solve a specific problem
+     - describe the machinery
+     - explain
+   * - *its form*
+     - a lesson
+     - a series of steps
+     - dry description
+     - discursive explanation
+   * - *analogy*
+     - teaching a small child how to cook
+     - a recipe in a cookery book
+     - a reference encyclopaedia article
+     - an article on culinary social history
+
+This division makes it obvious to both author and reader what information goes where. It tells the author how to write, and what to write, and where to write it. It saves the author from wasting a great deal of time trying to wrestle the information they want to impart into a shape that makes sense, because **each of these kinds of documentation has only one job**.
+
+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.
+
+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.
+
+
+What about project (rather than product) documentation?
+-------------------------------------------------------
+
+You may well ask: where do things like changelogs, contribution policies, and other information about the project fit into this scheme? The answer is that they do not - because they are, strictly speaking, project documentation rather than documentation of the producr itself,
+
+They can simply be kept in appropriately-named sections alongside the other material - as long as they are not mixed up *in* it.
+
+With that in mind, let's explore each of the four key functions.