Published quality and compass notes

.gitignore

@@ -3,3 +3,4 @@ _build
 .DS_Store
 __pycache__
 .idea/
+stashed/

_static/diataxis.css

@@ -22,6 +22,7 @@ article aside.sidebar {background: #ccc;}
 .sidebar-drawer {
     width: calc(50% - 28em);
     min-width: 13em;
+    justify-content: space-around;
 }
 .sidebar-container, .toc-drawer {
     width: 12em;

adoption.rst

@@ -43,7 +43,7 @@ bodies of documentation. In some cases the adoption remains partial or is still
 * `Cloudflare Workers docs <https://blog.cloudflare.com/new-and-improved-workers-docs/>`_ (related article, `New and
   improved Workers Docs <https://blog.cloudflare.com/new-and-improved-workers-docs/>`_)
 * `corrux <https://corrux.io/>`_ (internal)
-* `Divio <https://docs.divio.com/>`_ (where Diátaxis was first developed)
+* `Divio <https://docs.divio.com/>`_
 * `Django <https://docs.djangoproject.com/en/dev/#how-the-documentation-is-organized>`_
 * `django CMS <https://docs.django-cms.org>`_
 * `edo <https://edo.readthedocs.io>`_, a library for Evolutionary Dataset Optimisation

compass.rst

@@ -0,0 +1,62 @@
+.. _compass:
+
+The compass
+=======================
+
+The Diátaxis map is an effective reminder of the different kinds of
+documentation and their relationship, and it accords well with intuitions
+about documentation.
+
+However intuitions is not always to be relied upon. Often when working with
+documentation, an author is faced with the question: *what form of
+documentation is this?* or *what form of documentation is needed here?* - and
+no obvious, intuitive answer.
+
+Worse, sometimes intuition provides an immediate answer that is also wrong.
+
+A map is most powerful in unfamiliar territory when we also have a compass to
+guide us.
+
+The Diátaxis compass is something like a truth-table or decision-tree of
+documentation. It reduces a more complex, two-dimensional problem to its
+simpler parts, and provides the author with a course-correction tool.
+
+
+.. list-table::
+   :widths: 33 33 34
+   :header-rows: 1
+   :stub-columns: 0
+   :class: wider
+
+   * - If the content describes...
+     - ...and serves the user's...
+     - ...then it must belong to...
+   * - practical steps
+     - study
+     - a tutorial
+   * - practical steps
+     - work
+     - a how-to guide
+   * - theoretical knowledge
+     - work
+     - reference
+   * - theoretical knowledge
+     - study
+     - explanation
+
+The compass can be applied equally to user situations that need documentation,
+or to documentation itself that perhaps needs to be moved or improved.
+
+To use the compass, two questions need to be asked:
+
+  Are we dealing with **practical steps** (action, something someone will *do*),
+  or are we dealing with **theoretical knowledge** (propositional knowledge,
+  information, something someone will only *think*)?
+
+and:
+
+  Are we dealing with **study** (the *acquisition* of skills and knowledge)
+  or **work** (the *application* of skills and knowledge)?
+
+Using the compass is itself something that becomes more effective and accurate
+with practice, but it quickly becomes a useful decision-making tool.

conf.py

@@ -35,7 +35,7 @@
 # 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', 'env', 'LICENSE.rst', 'README.rst']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'env', 'LICENSE.rst', 'README.rst', 'stashed/']
 
 
 # -- Options for HTML output -------------------------------------------------

index.rst

@@ -1,15 +1,15 @@
 .. meta::
    :description:
-       The Diátaxis framework solves the problem of structure in technical documentation, making it easier to
-       create, maintain and use.
-   :keywords: documentation, four, kinds
+       The Diátaxis framework solves a problem of quality in technical documentation, describing an
+       information architecture that makes it easier to create, maintain and use.
+   :keywords: documentation, four, kinds, architecture
 
 .. _diataxis:
 
 Diátaxis
 ========================================================
 
-..  rubric:: A systematic framework for technical documentation authoring.
+..  rubric:: A systematic approach to technical documentation authoring.
 
 ----------
 
@@ -19,8 +19,10 @@ Diátaxis
 
     -- David Laing
 
-The Diátaxis framework aims to solve the problem of structure in technical documentation. It adopts a systematic
-approach to understanding the needs of documentation users in their cycle of interaction with a product.
+
+Diátaxis is an approach to :doc:`quality <quality>` in technical documentation. It describes
+an information architecture that emerges from a systematic approach to understanding the needs of
+documentation users.
 
 ..  sidebar::
 
@@ -30,30 +32,30 @@ approach to understanding the needs of documentation users in their cycle of int
 Diátaxis identifies four modes of documentation - **tutorials**, **how-to guides**, **technical reference** and
 **explanation**. It derives its structure from the relationship between them.
 
-In Diátaxis, each of these modes (or types) answers to a different user need, fulfils a different purpose and requires
-a different approach to its creation.
+In Diátaxis, each of these modes (or types) corresponds to a different user need. Each fulfils a
+different purpose and requires a different approach to its creation.
 
 .. image:: /images/diataxis.png
    :alt: Diátaxis
    :class: wider
 
-Technical documentation should be structured explicitly around these four types, and should keep them all separate and
+Technical documentation should be structured explicitly around these four types, and should keep them separate and
 distinct from each other.
 
 In other words, what we call *documentation* is fundamentally not one thing, but four. Understanding the implications
 of this, and how those four different things work, can help improve most documentation.
 
 ..  epigraph::
 
-    While redesigning the `Cloudflare developer docs <https://developers.cloudflare.com>`_, this content framework
-    became our north star for information architecture. When we weren’t sure where a new piece of content should fit
-    in, we’d consult the framework. Our documentation is now clearer than it’s ever been, both for readers and
-    contributors.
+    While redesigning the `Cloudflare developer docs <https://developers.cloudflare.com>`_, Diátaxis became our north
+    star for information architecture. When we weren’t sure where a new piece of content should fit in, we’d consult
+    the framework. Our documentation is now clearer than it’s ever been, both for readers and contributors.
 
     -- Adam Schwartz (`@AdamSchwartz <https://github.com/adamschwartz>`_)
 
-Diátaxis promises to make documentation and projects better, and the teams that work with them more successful. It is
-light-weight, easy to understand and straightforward to apply. It doesn't impose implementation constraints.
+Diátaxis is light-weight, easy to understand and straightforward to apply. It doesn't impose implementation
+constraints. It brings an active principle of quality to documentation. It helps make projects, and the teams that work
+with them, more successful.
 
 Diátaxis is :ref:`proven in practice <adoption>` across a wide variety of fields and applications, in large
 and small, open and proprietary documentation projects.
@@ -75,8 +77,11 @@ and small, open and proprietary documentation projects.
    :hidden:
    :titlesonly:
 
-   needs
    Tutorials vs how-to guides <tutorials-how-to>
+   Reference vs explanation <reference-explanation>
+   needs
+   compass
+   quality
    how-to-use-diataxis
 
 .. toctree::

needs.rst

@@ -1,64 +1,103 @@
 .. _needs:
 
-Understanding users' needs
+The map of needs
 =============================
 
-Diátaxis isn't just a system for structuring documentation, it's a framework for understanding it, guiding the
-work of documentation authors, and assessing the quality of documentation. However its most obvious implication
-is for documentation structure.
+*How to organise my documentation?* In the absence of a clear, generalised
+documentation architecture, documentation creators will usually try to
+structure their work around characteristics or features of the product its
+intended to serve.
 
+This is rarely successful, even in a single instance. In a portfolio of
+documentation instances, the results are wild inconsistency. Much better is
+the adoption of a scheme that tries to provide an answer to the
+question: how to arrange documentation *in general?*
 
-The problem of structure
---------------------------
+In fact any orderly attempt to organise documentation into clear content
+categories will help improve it (for authors as well as users), by providing
+lists of content types.
 
-Of all the problems that bedevil authors and maintainers of documentation, the problem of *structure* is one that
-accounts for a significant proportion of the grief they suffer. Multiple different documentation architectures exist
-that try to provide a solution to this problem. Any orderly attempt to organise documentation into clear content
-categories will help improve it (for authors as well as users).
+Even so, authors often find themselves needing to write particular
+documentation content that fails to fit well within the categories put
+forward by a scheme, or struggling to rewrite existing material. Often,
+there is a sense of arbitrariness about the structure that they find
+themselves working with - why this particular list of content types
+rather than another? And if another competing list is proposed, which to
+adopt?
 
-However, even when armed with a helpful structure, authors often find themselves needing to write particular
-documentation content that seems to falls outside the scheme it provides, or across its internal boundaries.
 
-The map
---------
+The Diátaxis map
+----------------------------------------------------
 
-Diátaxis aims to solve this problem by providing a scheme that prescribes documentation structure based on a systematic
-description and analysis of **user needs** (and not upon the characteristics of the product documentation is intended
-to serve, or around the different kinds of things that the documentation creator feels need to be said about the
-product).
+The most immediately striking feature of Diátaxis is its map:
 
-Diátaxis provides a *map* of distinct documentation types rather than a mere list, and specifies these types in such a
-way that the structure always naturally helps shape the content into an appropriate form.
+.. image:: /images/diataxis.png
+   :alt:
+   :class: wider
 
-The result is documentation that is not only better, but takes less effort to create and maintain.
+It's a memorable and approachable idea.
 
+One reason is that it is effective as a guide to organising documentation is
+that describes a **two-dimensional structure**, rather than a *list*. It
+specifies its types of documentation in such a way that the structure
+naturally helps guide and shape the material it contains.
 
-Axes of knowledge
---------------------------
+As a map, it places the different forms of documentation into relationship
+with each other. Each one occupies a space in the mental territory it outlines,
+and the boundaries between them highlight their distinctions.
 
-It's important to understand that Diátaxis is intended to apply to documentation pertaining to a *practical craft*, a
-*technical skill* - such as the use of a product. Successful exercise of any such craft or skill involves both
-theoretical grasp (knowledge and understanding), and an ability to apply that in practice, to work with the tools and
-materials of the craft.
+The result is documentation that is not only better, but takes less effort to
+create and maintain - but that is only possible because the Diátaxis map is a
+map of *needs*.
 
-Diátaxis divides documentation across two axes of knowledge: *theory/practice*, and *acquisition/application*.
 
-Documentation therefore either *contains theoretical knowledge* or *describes practical actions*, and is concerned
-either with serving *our acquisition* or *our application* of knowledge. Hence the map, across which the four forms
-of documentation are laid out:
+Needs
+-----
 
-.. image:: /images/diataxis.png
-   :alt:
-   :class: wider
+A map is only useful if it adequately describes a reality. Diátaxis is
+underpinned by a systematic description and analysis of generalised **user
+needs**.
+
+The user whose needs Diátaxis serves is *the practitioner in a domain of
+skill*. A domain of skill is defined by a craft - the use of a tool
+or product is a craft. So is an entire discipline or profession. Using a
+programming language is a craft, as is flying a particular aircraft, or even
+being a pilot in general.
+
+The successful engagement in any such craft or skill involves
+both *theoretical grasp* (knowledge and understanding), and an ability to
+apply that *in practice*, to work with the tools and materials of the craft.
+Documentation serving the practitioner must therefore meet the needs both
+of **theory** and its **practical application**.
+
+And at any moment in their craft, a practitioner is either *acquiring* their
+skill, or *applying* it to actual work. That is, a practitioner is either in
+the mode of **study** (learning, acquiring, building up their skill) or the
+mode of **work** (applying, using, exercising it). And this gives
+documentation two more needs to meet.
+
+
+Axes of knowledge
+--------------------------
+
+Diátaxis uses this analysis to divide documentation across two axes of
+knowledge: *theory/practice*, and *acquisition/application*.
+
+Documentation therefore either *contains theoretical (i.e. propositional)
+knowledge* or *describes practical actions*, and is concerned either with
+serving *our acquisition* or *our application* of knowledge. Hence the map,
+across which the four forms of documentation are laid out.
 
 
 
 Characteristics of documentation
 ----------------------------------------------------
 
-A clear advantage of organising material this way is that it provides both clear *expectations* (to the reader) and
-*guidance* (to the author). It's clear what the purpose of any particular piece of content is, it specifies how it
-should be written and it shows where it should be placed.
+A clear advantage of organising material this way is that it provides both
+clear *expectations* (to the reader) and
+*guidance* (to the author). It's clear what the purpose of any particular
+piece of content is, it specifies how it should be written and it shows
+where it should be placed.
 
 .. list-table::
    :widths: 16 21 21 21 21