In June 2024, my colleagues in the documentation team have mentioned to me an approach to writing, improving and structuring documentation, called Diátaxis, that I'm exploring as a possible way to improve my own admittedly haphazard writings.
It organises writing according to two axes
: a do-think (or
action-theory, about what kind of need-to-know the documentation addresses) axis
and a get-use (or learn-apply, or study-work, the reader's activity supported by
the documentation) axis. The get+think quadrant explains to foster
understanding (this is what most of my pages are, at least, trying to do). The
get+do one holds tutorials (lessons) to help learn. The use+do quadrant has
how-to guides (recipes) focused on specific goals. The use+think quadrant
provides information through reference texts (compendia of facts) – which
my descriptions of my notation should probably
aim to be.
Another way to describe the same classification is to think of the upper half of the diagram, tutorials and how-to, as instruction – they tell you what to do, in the imperative – and the lower as information, so the do-think axis can be thought of as the instruct-inform axis, while the left side contains narratives and the right is compendious, so we can think of the get-use axis as narrate-catalogue.
For all the water-fall
and even scrum-like planners out there,
here's a
quote
There's a strong urge to work in a cycle of planning and execution in order to work towards results. But it's not the only way, and there are often better ways
Although that sentence goes on to end when working with
documentation
, I consider the cycle
it offers
instead – chose something, assess it, decide what to do, do it, move
on – is more broadly applicable.
And, since it's what that guidance advises, I'll now commit my latest change to this page and move on to the next thing, trusting that when I have more to say I'll be back here to say it.
Written by Eddy.