diff --git a/.gitignore b/.gitignore index e46ec10..ff53e41 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,4 @@ _build .DS_Store __pycache__ .idea/ +stashed/ diff --git a/_static/diataxis.css b/_static/diataxis.css index 8132a8a..8430e3b 100644 --- a/_static/diataxis.css +++ b/_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; diff --git a/adoption.rst b/adoption.rst index 17f944e..1f5aae9 100644 --- a/adoption.rst +++ b/adoption.rst @@ -43,7 +43,7 @@ bodies of documentation. In some cases the adoption remains partial or is still * `Cloudflare Workers docs `_ (related article, `New and improved Workers Docs `_) * `corrux `_ (internal) -* `Divio `_ (where Diátaxis was first developed) +* `Divio `_ * `Django `_ * `django CMS `_ * `edo `_, a library for Evolutionary Dataset Optimisation diff --git a/compass.rst b/compass.rst new file mode 100644 index 0000000..4add34f --- /dev/null +++ b/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. diff --git a/conf.py b/conf.py index fafc08e..bbd6367 100644 --- a/conf.py +++ b/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 ------------------------------------------------- diff --git a/index.rst b/index.rst index 341d718..6810bca 100644 --- a/index.rst +++ b/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 ` in technical documentation. It describes +an information architecture that emerges from a systematic approach to understanding the needs of +documentation users. .. sidebar:: @@ -30,14 +32,14 @@ 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 @@ -45,15 +47,15 @@ of this, and how those four different things work, can help improve most documen .. epigraph:: - While redesigning the `Cloudflare developer docs `_, 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 `_, 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 `_) -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 ` 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 + Reference vs explanation + needs + compass + quality how-to-use-diataxis .. toctree:: diff --git a/needs.rst b/needs.rst index 3adee43..75851a6 100644 --- a/needs.rst +++ b/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 diff --git a/quality.rst b/quality.rst new file mode 100644 index 0000000..a2bd7ea --- /dev/null +++ b/quality.rst @@ -0,0 +1,161 @@ +Quality in documentation +========================= + +Diátaxis is an approach to *quality* in documentation. + +Functional quality +------------------ + +We need documentation to meet standards of *accuracy*, *completeness*, +*consistency*, *usefulness*, *precision* and so on. We can call these +aspects of its **functional quality**. Documentation that fails to meet +any one of them is failing to perform one of its key functions. + +These properties of functional quality are all independent of each other. +Documentation can be accurate without being complete. It can be complete, but +inaccurate and inconsistent. It can be accurate, complete, consistent and +also useless. + +Attaining functional quality means meeting high, objectively-measurable +standards in multiple independent dimensions, consistently. It requires +discipline and attention to detail, and high levels of technical skill. + +To make it harder for the creator of documentation, any failure to meet +all of these standards is readily apparent to the user. + + +Deep quality +------------ +There are other characteristics, that we can call **deep quality**. + +Functional quality is not enough, or even satisfactory on its own as an +ambition. True excellence in documentation implies characteristics of quality +that are not included in accuracy, completeness and so on. + +Think of characteristics such as: + +* *feeling good to use* +* *having flow* +* *fitting to human needs* +* *being beautiful* +* *anticipating the user* + +Unlike the characteristics of deep quality, they cannot be checked or +measured, but they can still be clearly identified. They are characteristics +of *deep quality*. + + +What's the difference? +--------------------------------------------------------------- + +Aspects of deep quality seem to be genuinely distinct in kind from the +characteristics of functional quality. + +Documentation can meet all the demands of functional quality, and still fail +to exhibit deep quality. For example, there are many examples of +documentation that is accurate and consistent, even useful, and yet +awkward and unpleasant to use. + +It's also noticeable that while characteristics of functional quality such as +completeness and accuracy are **independent** of each other, those of deep +quality are hard to disentangle. *Having flow* and *anticipating the user* +are aspects of each other - they are **interdependent**. It's hard to see how +something could feel good to use without fitting to our needs. + +Aspects of functional quality can be measured - literally, with numbers, in +some cases (consider completeness). That's clearly not possible with +qualities such as *having flow*. Instead, such qualities can only be enquired +into, interrogated. Instead of taking **measurements**, we must make +**judgements**. + +Functional quality is **objective** - it belongs to the world. Accuracy of +documentation means the extent to which it conforms to the world it’s trying +to describe. Deep quality can’t be ascertained by holding something up to the +world. It’s **subjective**, which means that we can assess it only in the light +of the needs of the subject of experience, the human. + +And, deep quality is **conditional** upon functional quality. Documentation can be +accurate and complete and consistent without being truly excellent - but it +will never be excellent without being accurate and complete and consistent. + +Finally, all of the characteristics of functional quality appear to us, as +documentation creators, as burdens and **constraints**. Each one of them +represents a test or challenge we might fail. Or, even if we have met +one *now*, we can never rest, because the next release or update means that +we'll have to check our work once again, against the thing that it's +documenting. Characteristics such as anticipating needs or flow, on the other +hand, represent **liberation**, the work of creativity or taste. To attain +functional quality in our work, we must *conform* to constraints; to attain +deep quality we must *invent*. + +.. list-table:: + :header-rows: 1 + + * - Functional quality + - Deep quality + * - independent characteristics + - independent characteristics + * - objective + - subjective + * - measured against the world + - assessed against the human + * - aspects of constraint + - aspects of liberation + * - a condition of deep quality + - conditional upon functional quality + + +Diátaxis and quality +-------------------- + +Diátaxis cannot address functional quality in documentation. It is concerned +only with certain aspects of deep quality. + + +Creating deep quality +~~~~~~~~~~~~~~~~~~~~~ + +Specifically, Diátaxis is concerned with meeting the needs of users by paying +attention to the correct organisation of documentation, and the arrangement +of its material and the relationships within it. It is concerned with the +form and language adopted in different parts of documentation. + +For example, Diátaxis is concerned with flow. In flow - whether the context is +documentation or anything else - we experience a movement from one stage or +state to another that seems right, unforced and in sympathy with both our +concerns of the moment, and the way our minds and bodies work in general. + +Most obviously, Diátaxis preserves flow by helping prevent the kind of +disruption of rhythm that occurs when a digression into explanation +interrupts a how-to guide. + +Or, it helps documentation fit user needs by constructing documentation +structure around them; its categories exist as a response to needs. + +But, while Diátaxis can help attain beauty in documentation, at least in its +overall form, it doesn't by itself *make documentation beautiful*. + +The characteristics of deep quality are forever being renegotiated, +reinterpreted, rediscovered and reinvented - what Diátaxis *can* provide is a +set of conditions for documentation in which they can be found, and therefore +has value in the creation of deep quality. + + +Exposing lapses in functional quality +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Although Diátaxis cannot serve functional quality in the same way, it can +fulfil a different role. + +It works very effectively to *expose* lapses in functional quality (it's often +remarked that one effect of applying Diátaxis to existing documentation is +that problems in it suddenly become apparent that were obscured before). + +For example: the Diátaxis approach recommends that :ref:`the architecture of +reference documentation should reflect the architecture of the code it +documents `. This makes gaps in the documentation much +more clearly visible. + +Or, moving explanatory verbiage out of a tutorial (in accordance with Diátaxis +demands) often has the effect of highlighting a section where the reader has +been left to work something out for themselves. diff --git a/reference-explanation.rst b/reference-explanation.rst new file mode 100644 index 0000000..256e2cb --- /dev/null +++ b/reference-explanation.rst @@ -0,0 +1,62 @@ +.. _reference-explanation: + +Explanation and reference +========================== + +Explanation and reference both belong to the *theory* half of the Diátaxis map - they don't contain +steps to guide the reader, they contain theoretical knowledge. + +The difference between them is - just as in the difference between tutorials and how-to guides - the +difference between the *acquisition* of skill and knowledge, and its *application*. In other words +it's the distinction between *study* and *work*. + + +A straightforward distinction, *mostly* +---------------------------------------- + +Mostly it's fairly straightforward to recognise whether you're dealing with one or the other. +*Reference*, as a form of writing, is well understood; it's used in distinctions we make about +writing from an early age. + +In addition, examples of writing are themselves often clearly one or the other. A tidal chart, +with its tables of figures, is clearly reference material. An article that explains *why* there +are tides and how they behave is self-evidently explanation. + +There are good rules of thumb. Lists (of components, such as classes or methods or attributes) and +tables of information will generally turn out to belong in reference. If it's boring and +unmemorable, it's probably reference. On the other hand, the only kind of documentation that someone +(a normal person, anyway) might read in the bath is explanation. + + +Intuition isn't reliable enough +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +We can say that mostly we can rely safely on intuition to manage the distinction. But only *mostly* +\ - because it's also quite easy to slip between one form and the other. + +It usually happens while writing reference material that starts to become expansive. For example, +it's perfectly reasonable to include illustrative examples in reference (just as an encyclopaedia +might contain illustrations) - but examples are fun things to develop, and it can be tempting to +develop them into explanation (using them to say *why*, or show *what if*, or how it came to be). + +As a result one often finds explanatory material sprinkled into reference. This is bad for the +reference, interrupted and obscured by digressions. But it's bad for the explanation too, because +it's not allowed to develop appropriately and do its own work. + +To help avoid being mislead by intuition, see :ref:`compass`. + + +Work and study +-------------- + +The real test though if we're in doubt about whether we're something is or is supposed to be +reference or explanation is: is this something someone would turn to while working, that is, while +actually getting something done, executing a task? Or is it something they'd need once they have +stepped away from the work, and want to think about it? + +These are two very fundamentally different *needs* of the reader, that reflect how, at that moment, +the reader stands in relation to the craft in question, in a relationship of *work* or *study*. + +Understanding those two relationships and responding to the needs in them is the key to creating +effective reference and explanation. + diff --git a/reference.rst b/reference.rst index 8abe7f2..1e5ab52 100644 --- a/reference.rst +++ b/reference.rst @@ -78,6 +78,8 @@ it - it is not a function of an encyclopaedia article to tell you what to do. Writing a good reference guide ---------------------------------------- +.. _respect-structure: + Respect the structure of the machinery ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/spelling_wordlist.txt b/spelling_wordlist.txt index 8ca88be..97fb396 100644 --- a/spelling_wordlist.txt +++ b/spelling_wordlist.txt @@ -1,8 +1,10 @@ +Colofon Diátaxis Dataset backend Ericsson equilibria +Fortran intubations Jupyter Chatbot diff --git a/tutorials-how-to.rst b/tutorials-how-to.rst index e24ba1b..45b757a 100644 --- a/tutorials-how-to.rst +++ b/tutorials-how-to.rst @@ -264,7 +264,7 @@ understand as a key distinction in making sense of what the user of documentatio The basic and the advanced -------------------------- -A common but understandable error is to see the difference between tutorials and how-to guides as being the difference +A common but understandable conflation is to see the difference between tutorials and how-to guides as being the difference between **the basic** and **the advanced**. After all, tutorials are for learners, while how-to guides are for already-skilled practitioners. Tutorials must cover