Introduction
From my days in academia working on my own research software to my current projects with chatbots and AI, I’ve been writing technical documentation in one form or another for years. Documentation comes rather naturally to me, and my formation as a linguist and educator is probably why I’ve been spending time reflecting on its practice.
For the past three months, I’ve been using the Diátaxis framework, both applying it to my own projects and thinking about why it works as well as it does. I found it through a job posting for a Technical Writer at Canonical (the company behind Ubuntu Linux). If you write documentation for a living, or if you’ve ever been on a team that had no idea where to start, I suggest checking it out. At its core, it argues for four kinds of documentation that should never get mixed: tutorials, how-to guides, reference, and explanation. I like the idea of it, and I think I can contribute to its foundations.
Here’s what I keep noticing as a linguist and educator: the framework has a great deal to say about what a piece of documentation is and what type of document it should be. But it says almost nothing about who is reading it and what that reader already brings with them. For a framework this concerned with language, that’s an odd gap, and it lands squarely in my own field.
Diátaxis, briefly
Diátaxis was developed by Daniele Procida, Director of Engineering for documentation at Canonical. Its central claim is derived from users’ needs along two axes:
- Action and cognition. A craft contains both practical knowledge (knowing how) and theoretical knowledge (knowing that). The distinction comes from the philosopher Gilbert Ryle in The Concept of Mind (1949), who, in its second chapter, argues that intelligence is both theoretical and practical.
- Acquisition and application. A practitioner both acquires a craft (study, practice) and applies it (work, hands-on).
Cross the two axes and you get four quadrants.
Image referenced from the Diátaxis website (Procida, n.d.)
The Foundations page of the framework is direct about what this entails:
“This is a complete map. There are only two dimensions, and they don’t just cover the entire territory, they define it. This is why there are necessarily four quarters to it, and there could not be three, or five. It is not an arbitrary number.” (Diátaxis, Procida, n.d.)
I think the need-analysis argument holds water. We can think of technical documentation as a kind of epistemic service: its purpose is closing a knowledge or skill gap for somebody, in whatever mode (theoretical or practical) they happen to be in.
The gap I see, from a linguistic and educational perspective
Here’s what I’ve run into in practice.
Imagine a PII anonymization framework, say for an email corpus (a project I worked on while at grad school: https://github.com/MCECorpus/MCEC-DeID). Written for privacy professionals, the data-protection ethics can stay implicit, because that ethic is part of what makes somebody a privacy professional in the first place. Written for software engineers, the same technical content is suddenly thinner. An engineer can implement k-anonymity perfectly well and never have had occasion to internalize why it matters. Same steps, same accuracy, but not the same document.
Or take a root cause analysis (RCA) framework as an example. For support engineers, its epistemic discipline is already part of their professional formation (“don’t confuse symptom with cause, don’t claim more than the evidence supports”). For a sales manager who needs the RCA output to build a pitch, it isn’t. Without that caution stated somewhere, an honestly hedged finding quietly becomes an overclaim in a slide deck.
Diátaxis has no mechanism for recipient design. The compass asks action or cognition? and acquisition or application? Both questions are about the content and the reader’s mode. Neither asks what the reader already brings to the table.
To be fair, the framework does list anticipating the user among the characteristics of “deep quality.” But the treatment is brief, and it lacks the rigor that the practical/theoretical axis gets:
We must pay attention to the correct organisation of these categories then, and the arrangement of its material and the relationships within them, the form and language adopted in different parts of documentation - as a way of fitting to user needs. (Diátaxis, Procida, n.d.)
Adding rigor through a competency framework lens
If I understand correctly, Diátaxis implies that documentation exists to help people close different types of gaps. It identifies those gaps by analyzing user needs. The map above is clear about this: a gap in learning is addressed by a tutorial, a gap in reaching a goal by a how-to guide, a gap in information by reference, and a gap in understanding by an explanation.
Each is a gap in knowledge or in skill.
That’s a natural place to stop if you think documentation serves knowledge and skill only. Above, I called documentation a sort of epistemic service, but I will take that back a bit. Those two terms are actually too narrow for what documentation is:
[…] the term knowledge applies to facts or ideas acquired by study, investigation, observation, or experience and refers to a body of information that is understood. The term skill is used to designate the ability to use one’s knowledge with relative ease to perform relatively simple tasks. (Rychen & Salganik, 2000, p. 8, bold emphasis is mine)
Now, imagine the documentation for an Identity Access Management system (here is an example of a project I worked on for the University of Arizona: ReData IAM Docs). Documentation like this is seldom aimed at only acquiring the knowledge of a system’s working parts or at performing simple tasks. Managing software identity is a complex endeavor involving different moving parts, permissions, and secrets. I argue that much of the documentation I’ve worked on is aimed at accomplishing complex tasks, which is already the terrain of competencies.
[…] the concept of competence refers to the ability to meet demands of a high degree of complexity, and implies complex action systems […] [C]ompetencies are structured around demands and tasks. Fulfilling complex demands and tasks requires not only knowledge and skills but also involves strategies and routines needed to apply the knowledge and skills, as well as appropriate emotions and attitudes, and effective management of these components. Thus, the notion of competencies encompasses cognitive but also motivational, ethical, social, and behavioral components. (Rychen & Salganik, 2000, p. 8)
Motivations and behaviours. Ethical and social components. These are part of what makes somebody competent, and Diátaxis has no axis that reaches them. Motivations and behaviours belong to the study of psychology and are outside my realm of expertise. Ethical and social components, however, are treated by the social sciences, and I will be focusing on them. French has a tidy vocabulary for these, so I’ll borrow it.
1. Savoir-être
French competency frameworks describe three things, all of them standard vocabulary in French professional training and HR practice:
- Savoir: knowledge, the theoretical kind. Diátaxis covers this on its cognition axis.
- Savoir-faire: know-how, the practical mastery of a task or tool. Diátaxis covers this on its action axis.
- Savoir-être: literally “knowing how to be.” The dispositions, judgment, and professional bearing somebody brings to the work. Diátaxis has no axis for this.
The educational version is even broader. UNESCO’s 1996 Delors report, Learning: The Treasure Within, proposes four pillars of learning: apprendre à connaître, apprendre à faire, apprendre à vivre ensemble, and apprendre à être (learning to know, to do, to live together, and to be, Delors et al., 1996). Diátaxis builds its foundations on the first two. The last two are not part of the foundations.
Savoir and savoir-faire can be fully externalized into text. That’s what makes them documentable at all. Savoir-être (let’s just call it “disposition” for convenience) resists it. Polanyi opened The Tacit Dimension (1966) with “we can know more than we can tell,” and the closest classical analogue is Aristotle’s phronesis, in Book VI of the Nicomachean Ethics: practical wisdom formed through experience rather than transmitted by proposition. Disposition is mostly acquired through apprenticeship, correction, and watching somebody competent do the thing, all of which documentation is bad at. However, as I will argue, there are cases where disposition needs to be included into the documentation: when an audience borrows a domain’s technical content without the professional formation that normally comes attached to it, the disposition has to come from somewhere. Sometimes, a document is the only channel available.
2. Register
The second gap isn’t about content at all, and it’s where my linguistics background gets to be useful.
Consider a language phenomenon that Sacks, Schegloff and Jefferson (1974) call “recipient design”, the observation that speakers tailor their language (words, styles, and references) according the people it’s addressed to. It isn’t an occasional phenmomenon either, but it is how language gets assembled in the first place.
For example, Isaacs and Clark (1987) asked New Yorkers to describe landmarks (in postal cards) to people who were either other New Yorkers or newcomers. Those describing the landmarks diagnosed how knowledgeable their counterparts were of the city within one or two turns into the conversation and rebuilt their language around it. Longtime residents got more proper names, novices got more descriptions. Same landmarks, same city, different language. The researchers framed this as a problem of common ground: people build language around what they think their addressee already knows, believes, and assumes (Isaacs and Clark, 1987, p. 26).
For the rest of the argument, I will be calling register the differences in language arising from recipient design. For example, if I, as the person in charge of documenting a software release process had to adapt the language in that documentation for QA testers, Customer Success managers, or Functional Support Analysts, I would be changing the register according to the audience. Two how-to guides can have identical instructions and still be different documents, differing in which warnings get bolded and which get a footnote, whether the safe option is the default or something you opt into, and how much competence the text extends to its reader.
Calling this variation in language register, however, is a simplification. And although this discussion belongs to a more academic setting, I’d like to briefly address other aspects of this concept of register. The Hallidayan school of Systemic Functional Linguistics analyses register along three parameters (Halliday & Hasan, 1985):
- Field: what is being talked about, the activity in play.
- Tenor: the relationship between participants, expert-to-expert versus expert-to-newcomer included.
- Mode: the channel, and how the language is organized rhetorically within it.
Register, in the sense I use it here, is a matter of tenor: how the document stands toward its reader, which can shift while the content stays fixed.
For documentation, the implication is this: there is no audience-neutral register. There are only registers you haven’t noticed yet. It’s the same trap as claiming that someone “does not have an accent”: the accent you don’t hear is just the one that matches your own. That claim isn’t superficial. Biber & Conrad (2009) shows extensively how situational factors create measurable differences in written language. Register is a set of linguistic choices that leave testable evidence, and it is present in all documents.
So, coming back from the linguistic expedition, disposition is content, register is form, and they belong in different places. Here is where I think they belong in Diátaxis:
- Disposition, when it has to be supplied, belongs only on the acquisition side: it can be shown by modeling in a tutorial, or told directly in an explanation. It has no business as content in a how-to guide or in reference. That’s precisely the interruption Diátaxis exists to prevent.
- Register is present in all four types because it is an inherent part of language. And once disposition is ruled out as content, register becomes the only channel through which a how-to guide or a reference page can relate to its reader at all.
The social dimension (vivre ensemble)
Both disposition and register follow from one thing you determine before drafting: who is this for, and what do they already carry? I will call it the “documentation brief”, as a parallelism to the translator’s “translation brief”, which is a set of specifications translators usually request from their client or project manager and includes the purpose, target audience, tone, and other factors. The “documentation brief” is where apprendre à vivre ensemble, the third Delors pillar, the “understanding of others” (Delors et al., 1996, p.20) enters the picture.
The audience portion of the documentation brief yields two outputs and one decision:
- A savoir-être decision on the acquisition side: is it needed, and if so, shown or told?
- A register guide for all forms of documentation: how much can be presumed, and how should this sound?
- A fork decision: if the gap between two audiences is wide enough that one needs an explanation the other would find condescending or useless, the documentation forks by audience before it forks by type.
One thing I want to be precise about: this sits above the four quadrants, not inside them. If savoir-être were a third value on the knowledge axis, it would have to cross acquisition and application symmetrically, the way savoir and savoir-faire do. It can’t. There is no coherent “savoir-être in application mode” document. There is nothing you consult mid-task to know how to be. Disposition is either present in you when you act, or it isn’t.
Final thoughts
Diátaxis derives four types of documents from two axes and then stops, correctly, because those axes exhaust the territory of the craft. But documentation doesn’t serve a craft in the abstract. It serves a particular practitioner, standing in a particular relation to that craft, arriving with some of it already formed in them and some of it not. The four types tell you what a document must be. They say nothing about what a document may presume. And, by its own nature, every document presumes something, whether or not its author chose it deliberately.
The documentation brief is how that presumption becomes a decision instead of an accident. Its two outputs are the same decision seen from either side of the map. On the acquisition side, disposition is supplied as content, because a reader who is studying can be told who to become. On the application side, disposition is encoded as register, because a reader who is working cannot be told anything they didn’t ask for. So the text carries its stance in its form, in what it warns about, what it defaults to, and how much competence it assumes.
This brings us back to the framework itself. Procida writes that Diátaxis can “lay down some conditions for the possibility of deep quality.” (Diátaxis, Procida, n.d.). Anticipating the user is on that list of conditions. What is currently missing is a the mechanism for doing that, and I don’t think that mechanism is exotic: ask who is reading, ask what they already carry, and let the answer decide both what you say and how you sound.
If you come at documentation from a practical direction, the ethical and social components of it can look like a detour. I assure you they are not. These are standard concepts applied in professional training, HR practice, education ministries and statistical offices. If documentation is to become the discipline with rigorous foundations that Procida argues for, we must think about the ethical and social components as part of those foundations.
Acknowledgements
The entirety of the work above is my own except for the re-worked Diátaxis map for which I used Claude Design. I used Claude (Anthropic) for help with organization, proofreading, and citation verification and formatting (I’ve always hated APA), and Grammarly for grammar and spell checking. Any errors are entirely my own.
References and readings
Aristotle. Nicomachean Ethics, Book VI. See also Kraut, R. (2022). Aristotle’s ethics. In The Stanford Encyclopedia of Philosophy. https://plato.stanford.edu/entries/aristotle-ethics/
Biber, D., & Conrad, S. (2009). Register, genre, and style. Cambridge University Press.
Delors, J., et al. (1996). Learning: The treasure within. Report to UNESCO of the International Commission on Education for the Twenty-first Century. UNESCO Publishing. https://unesdoc.unesco.org/ark:/48223/pf0000109590
France Travail. (n.d.). Les 3 types de compétences à valoriser lors de votre candidature. https://www.francetravail.fr/candidat/vos-recherches/preparer-votre-candidature/accompagne-dans-sa-recherche/les-3-types-de-competences-a-v-1.html
Halliday, M. A. K., & Hasan, R. (1985). Language, context, and text: Aspects of language in a social-semiotic perspective. Deakin University Press.
Isaacs, E. A., & Clark, H. H. (1987). References in conversation between experts and novices. Journal of Experimental Psychology: General, 116(1), 26–37.
Polanyi, M. (1966). The tacit dimension. Doubleday. https://press.uchicago.edu/ucp/books/book/chicago/T/bo6035368.html
Procida, D. (n.d.). Diátaxis. https://diataxis.fr/
Procida, D. (n.d.). Work in documentation. https://vurt.org/work-in-documentation/
Rychen, D. S., & Salganik, L. H. (2000). Definition and selection of key competencies. A contribution of the OECD program Definition and Selection of Competencies (DeSeCo). Swiss Federal Statistical Office. https://www.deseco.ch/bfs/deseco/en/index/02.parsys.69356.downloadList.26477.DownloadFile.tmp/2000.desecocontrib.inesg.a.pdf
Ryle, G. (1949). The concept of mind. Hutchinson. See also Tanney, J. (2024). Gilbert Ryle. In The Stanford Encyclopedia of Philosophy. https://plato.stanford.edu/entries/ryle/
Sacks, H., Schegloff, E. A., & Jefferson, G. (1974). A simplest systematics for the organization of turn-taking for conversation. Language, 50(4), 696–735.
