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) axis and a get-use (or learn-apply) 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 and the
use+think quadrant provides information through reference texts (compendia of
facts) – which my descriptions of my
notation should probably aim to be.
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 ends 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 the change that adds this beginning of a page, along with changing a link elsewhere to point here, 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.