Skip to content

Latest commit

 

History

History
62 lines (47 loc) · 1.94 KB

compass.rst

File metadata and controls

62 lines (47 loc) · 1.94 KB

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 intuition 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.

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.