You don't have to say everything exactly once.
Until being exposed to this idea I always tied myself in knots trying to write one stream of text that serves as THE DOCS. It's impossible to do this well (once you know, it seems very obvious haha). Just realising that you can write the same info in different ways for different readers is very helpful!
By giving 2-3 examples, that describe the same thing from slightly different aspects, you can to some extent overcome the ambiguities of language, by letting the reader figure out the common denominator between those examples, which will be a lot less ambiguous that only telling it from one example.
Let me give you two examples more [...] ;)
(Related, this is a technique used extensively by writers like king Solomon in the book of Proverbs in the Bible.)
Separately, I've heard that the Nicene Creed and its ancillaries had the repetitions hardcoded to forestall natural schism/emergent mutations in the generational belief system.
I have more sympathy with intro and outro summaries, as long as the bullet points are short and delivered one at a time while the speaker expands upon each one.
Slides should be a visual aid, not a substitute for presentation.
- The introduction should announce the thesis and its development - walk your way towards your thesis - The conclusion should summarize your thesis (and hint at openings towards new grounds)
But somehow, everyone seems to forget it and is in awe whenever someone recaps it.
And even if it eventually is fixed it is not obvious that the reason for the bug was that the documentation was wrong in one particular place.
It's messy.
= abstract 1) in this paper we show that X holds by evaluating Y against Z = intro 2) the problem of A is important because B, however the X aspect was overlooked; we show that evaluating Y highlights real world challenges, in contrast to Z, that... 3) to sum up, we found that Y is better at Z because X = related work Z approached the problem as..., which improved..., but as we show further, this is not sufficient to achieve...
.. and so on - you circle around the main message over and over again in each section.
...even the source code itself "says", in its own way, the same thing as the documentation, just to a different "audience" (the compilers)
The slightly ironic part is that the Diataxis docs themselves are a bit obtuse. It's a little verbose. So it took a couple passes for it all to click.
The analogy I gave my team that was helpful for everyone's understanding:
Imagine you're shopping for a piece of cooking equipment, like a pressure cooker.
The first thing you're going to look at is the "quickstart" (tutorial) – how does this thing work generally? You just want to see it go from A to B.
Then, you're going to wonder how to use it to cook a particular dish you like. That's a how-to.
If you're really curious about anything you've seen so far, then you'll flip to the reference to read more about it. For example, you might check the exact minutes needed for different types of beans.
And finally, when you're really invested in pressure cooking and want to understand the science behind it - why pressure affects cooking times, how the safety mechanisms work, etc. - that's when you'll read the explanatory content.
Comically, our docs were completely backwards: we lead with explanation ("How Sequin Works"). I think that's the natural impulse of an engineer: let me tell you how this thing works and why we built it this way so you can develop a mental model. Then you'll surely get it, right?
While that may be technically accurate, a person doesn't have the time or patience for that. You need to ramp them into your world. The quickstart -> how-to -> reference flow is a great way to do that. Then if you really have their attention, you can galvanize them about your approach with explanatory material.
[1] https://sequinstream.com/docs
PS: If you have any feedback on our docs, lmk :)
Minor note: The only thing in your docs that made me pause was the repeated use of "CDC", which I had to google the definition of. (For context, I have implemented "CDC" several times in my career, but wasn't familiar with the acronym)
https://github.com/sequinstream/sequin/commit/28bfba603da6d2...
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ab...
I'm also aware of https://developer.mozilla.org/en-US/docs/Web/HTML/Element/df... but I think it has more nuance to it and for sure involves having a lot more supporting structure in the document
What’s a CDC?
On the other hand, systems like these might miss out on what users actually need. Diátaxis might work for a long time if technical documentation is only used in a documentation platform. However, if the same information could and should be used in more than one place—for example, in a UI, in a documentation portal, and in a mobile app—there might be need to break up information into smaller pieces in order to assemble them in different ways. This is known as 'content reuse', the practice of using the same content in multiple places. One approach on how to create and edit information for content reuse is described in the 'every page is page one' concept: https://everypageispageone.com/the-book/
If there's resources and time, I always recommend to do UX research at the very start of a project so that one doesn't later feel choked by a severely restricted information model. Nielsen/Norman have done a lot of research in this area and have interesting propositions on how to resolve issues around all of this, for example: https://www.nngroup.com/articles/information-foraging/#toc-w...
I don't see it. DITA differentiates between topic types such as task, reference, concept, etc., but a tutorial or a solution guide will be a combination of those topic types. Here I believe the focus is on deliverables that are larger than the individual topic.
FWIW if you break up your content into reusable chunks and mark it up (with DITA or Docbook semantics, say), it should be a lot more amenable to being "understood" by a LLM... but I have not seen any data on this.
We do see people try to take it too far though and have literally only these four categories on their docs page, which never works well imo.
It's mainly useful for a writer to keep in mind stuff like "it's a guide so focus on getting to result, not teaching" but in reality you don't want super hard lines. It's OK to have a bit of tutorial in a guide.
Only? For many projects having a medium quality version of just one of those would be an improvement.
----
Where the approach hits a wall in practice I think is when there is a lack of interconnection between the quadrants. E.g. for software frameworks, if the guides lack links to the references for specific classes/methods (which you ultimately will have to use), that makes exploring the surrounding context a lot harder. I have a few concrete frameworks in mind where there is a split along the quadrants and that's one of the biggest annoyances about their docs.
Are you seeing experienced people cargo-culting or simply beginners to the framework being religious in its application?
I distinguish the two because I find that, when there's no other expert, a beginner is better off being dogmatic than trying to "do the right thing." By definition, a beginner does not have the expertise to make this decision. As you gain experience, you'll start to see where you need to deviate from the established rules.
Think of it like home-cooking to a recipe book vs being a professional chef throwing things in a pot to feel and taste.
I see it as a useful guide like any methodology should be. But I have worked with someone who insisted the rules should be followed to the letter, literally not a single sentence of explanation in any tutorial. So yes, that is the danger of these systems.
Treating a SHOULD as a MUST even when particular circumstances are against it, is one way to fail at a task.
It's like Orwell's last rule, where many people seem to miss that it's the punchline of the whole essay: "Break any of these rules sooner than say anything outright barbarous."
> This piece appears to be primarily an Explanation with some elements of Reference mixed in. This documentation appears to be trying to serve multiple purposes, which according to Diátaxis is not ideal. The mix makes it less effective at both explaining and serving as reference. Following Diátaxis principles, this content might be better split into: 1) A pure explanation section about the concept and importance of hyperparameter tuning, and 2) A separate reference section listing the specific tools and methods available.
> This blending of documentation types is exactly what Diátaxis warns against when it says "Unfortunately, too many software developers think that auto-generated reference material is all the documentation required" and "The writer, intent on covering the topic, feels the urge to include instruction or technical description related to it. But documentation already has other places for these."
> HOWEVER. Let's look at why this integrated approach works well in a User Guide context:
> Natural Learning Flow: The documentation follows how people actually learn and use tools: 1) First understand what hyperparameters are, 2) Learn why you might want to tune them, 3) See what tools are available, 4) Get pointed to practical implementation examples
> Contextual Knowledge: By integrating explanation with technical details, users can immediately connect concepts to implementation. There's no need to jump between different documentation sections to piece together understanding.
> Progressive Disclosure: The documentation starts with fundamental concepts and progressively introduces more complex tools and considerations. This scaffolding helps users build understanding naturally.
> Practical Value: By combining explanation with specific tools and methods, users can immediately apply what they're learning. The documentation bridges theory and practice.
I'm always a bit leery of "dogmatic" approaches, though, because they tend to develop a "priesthood," that refuses to bend; even when reality demands it.
In my experience, the initial developers of the dogma use it to marvelous effect, but subsequent "priests" screw the pooch; sometimes, turning the approach into a curse. Many good ideas have been destroyed by too-rigid applications (What is "Agile"?).
I see any documentation as having basically two faces: The maintainer, and the user. Each, has drastically different needs, and should probably be addressed by completely different teams.
As has been alluded to, in other comments, you can have issues with multiple instances of documentation, falling out of sync (the curse of most wiki-style documentation), but results matter. If the multiple instances can be effectively synced, then the documentation is effective and useful to its consumers. If no one reads the perfectly formatted and synced documentation, it's worthless.
On SNL, Phil Hartman[n] used to play The Anal-Retentive Chef. In one skit, he spent so much time prepping, that he couldn't actually demonstrate the recipe.
I see a lot of that, in tech. Toolchains and libraries that are absolutely perfect, but are unusable, in practice.
Documentation is an amalgam of many disciplines; human nature/psychology, graphic design, information architecture, technical infrastructure, publishing and distribution, etc.
I really think it's often treated as an afterthought, in most projects, and I believe that it should be a first-class consideration, at the Requirements stage, onwards.
I strongly suspect that few of the originators of dogma considered their work as such.
As I have gotten older, I have learned that "It Depends" is the only true dogma for almost all aspects of my life.
This is an interesting perspective that I disagree with. You seem to be saying that a general misunderstanding or misapplication of a good idea degrades the idea to a point that "destroys" it.
On the contrary, I believe there is experience to be gained in practice: either the initial idea wasn't good after all, in which case we're destroying an illusion; or the poor examples serve to refine the idea by clarifying some ambiguity that, interpreted wrongly, leads to failure.
Perhaps your argument is that many people may become familiar with the bad implementations and the idea's popularity will decline, depressing demand for refined implementations. This is likely true, but reflects the tragedy of the anticommons, not a degradation in the idea itself.
There's an old Swiss Army saying "When the map and the terrain disagree, believe the terrain.".
People who invest in dogma, refuse to look at the terrain. The map is The Only Source of Truth.
I believe that most dogma comes from something that works in one or more contexts, and may actually be highly effective, in other contexts, as long as it is adjusted for context. That last part, is what kills it. People refuse to change, and the dogma gets a bad name as a "failure."
You see this constantly.
It shifts the focus from trying to cram everything into one ‘perfect document’ to recognizing that different users have different needs.
Like, tutorials are for learning by doing, guides are for solving specific problems, reference is for quick lookups, and explanations dive into the ‘why.’
That clarity alone can make one write useful docs.
That being said, sticking too rigidly to any system can be a trap.
I would say the author's Divio re-write at Diataxis.fr is less cluttered in its graphic but still essentially the same as the one that was used at Divio. I've always viewed the two references, for all intent and purpose, the same document for the ideas being presented in the context of their specific websites.
• “Most useful when we're studying” and “Most useful when we're working” are clearer (and also more precise!) than abstract (“chunking”) terms like “Acquisition” and “Application”.
• Similarly, “Practical steps” and “Theoretical knowledge” are clearer than “Action” and “Cognition”.
• For that matter, the “-oriented” suffix in “Learning-oriented”, “Problem-oriented”, “Understanding-oriented”, “Information-oriented” is helpful, compared to the “Learning”, “Goals”, “Understanding”, “Information” abstract nouns.
What is common to all three sets of differences is that the former labels (on the older diagram) actually carry with them their semantic category (what kind of difference is being described, namely: (1) when useful, (2) what contents, (3) what's the orientation), while in the newer diagram everything is just abstract nouns. (E.g. “Useful during application” and “Useful during acquisition” would still be an improvement over just “Application” and “Acquisition”, though the older labels are even more direct and clear, without requiring the reader to engage in psychology to think abstractly about terms like acquisition.)
Also (separate complaint), whenever I want to tell anyone else about this "four kinds of documentation" approach, I always link to the archived https://web.archive.org/web/20200312220117/https://www.divio... which is the latest version that is entirely on a single page. Both the current version on the Divio site and on the Diataxis site seem “overdone”; a prospective reader has to click on “next” several times and it's unlikely they're going to do that.
That's a mistake in my opinion. The big compass of four kinds of documentation I eye-catching and memorable, and I am sure it is part of the success of Diátaxis.
But what gets me out of trouble in my own work every time is https://diataxis.fr/compass/. It's one thing to have the general idea; it's another to be armed with an effective tool to apply to work.
The site doesn't just contain opinions and ideas, it also contains tools, that really are worth using.
[Maybe diataxis.fr itself should be more clearly organized into an overview page (“explanation”), and separate sections for How-to guides and Reference. Right now it has an “Applying Diátaxis” and “Understanding Diátaxis” with a suggestion to start at the former, when in fact what I like most about documentation organized per the philosophy is that I as a reader can choose to start at the “Understanding” pages, instead of reading through tutorials and how-to guides and reference pages when I have not yet chosen to adopt whatever is being documented.]
Acquisition := Most useful when we're studying
Application := Most useful when we're working
Cognition := Theoretical knowledge
Action := Practical steps
Glad to learn that you've given your system a discoverable name though; for years since that PyCon presentation, I've informally recalled it as "the idea by that Django documentation guy".
During a sprint I was told that the docs I was preparing (not by Daniele, for the record) were mixing modalities and not acceptable because of this. Not pulling rank, but I've been a teacher for 20+ years, and I have a reasonable ida of how to explain things and how to scaffold learning so that people can both get things done and progress with understanding happening as part of that.
As long as there's not total rigidity then this is a great tool for deciding how to produce documentation and what each type of document should do. I often see examples in documentation (numpy springs to mind) where the examples could be a lot better chosen rather than 'magic from the sky'. A good, well chosen example can provide a lot of learning while illustrating usage, a corner case or other things to be aware of.
If that set of labels doesn't work for you, there are many other ways that the Diataxis doc attempts to explain the differences. You might find it a useful exercise to seek terms that make more sense to you. Or just to try to understand them in other ways - e.g. via the action/cognition ("do vs. think") and acquisition/application ("at study vs. at work") dichotomies.
There's an entire page devoted to distinguishing tutorials from how-to guides (https://diataxis.fr/tutorials-how-to/). (Note that this is itself classified as "understanding" material; as an exercise, you could try to evaluate the writing there to see how it maps onto what is described as "explanation", and doesn't map onto how a "tutorial" is supposed to work.)
But to me, one of the simplest distinctions is that a "tutorial" is the sort of thing that you can't do on Stack Overflow. That's because a tutorial involves following a lesson plan that was set by a teacher, who fills in the student's unknown unknowns. On Stack Overflow you must ask a question; a tutorial is material for someone who doesn't yet know what to ask.
There are plenty of extraordinarily popular questions on Stack Overflow that ask how to do some simple task. But to work in the format, you have to ask, not simply request help (see also: https://meta.stackoverflow.com/questions/284236).
Their doc actually explains the difference efficiently though :
Tutorials - learning-oriented experiences
How-to guides - goal-oriented directions
Reference - information-oriented technical description
Explanation - understanding-oriented discussion
I guess that's still better than labelling them Type I-IV tutorials.
The lecture is the explanation. The tutorial/lab is a guided experience (Microsoft's fake Contoso company comes to mind). A how-to guide is what you need when you want to search/chatgpt a solution. Reference material: thesaurus, encyclopedia, owner's manual.
Video games have built-in tutorials and yet walkthrough guides are still necessary for tricky puzzles. You check the key bindings as reference.
Yes, one is focused on understanding (mechanics, lore, UI) and the other is focused on a specific task (do these steps to progress).
Diataxis is not inventing these words - it is using them deliberately. You seem unwilling to actually [learn what they mean](https://chatgpt.com/share/6751d9b7-3fd4-800a-8b81-1949069007...).
I explain it in a more audience focused way:
An explanation is for a prospective customer.
A tutorial is for someone who's never used it before.
A how-to is for someone familiar with it but doesn't use that particular feature often enough to memorize it.
A reference is for people wanting to become an experts on the product.
Here is a extract from Ubuntus page about this:
> Writing security reference documentation, you will know that you should be producing clear and simple statements of fact. Explanation of a security feature or function, or showing how to use it – those don’t belong here. There is a place for them: a different place. If those things are required, then there should also be a security explanation topic, or a security how-to guide. This immediately makes life easier for the documentation author, who recognises that explaining and showing how-to are also important.
https://ubuntu.com/blog/diataxis-a-new-foundation-for-canoni...
That's different from a how-to, talking someone through a problem.
- first you make a "raw" corpus, with all the information needed to produce an answer
- then you generate sample question-answer pairs
- then you use AI to make better questions and better answers (look at e.g. WizardLM https://arxiv.org/pdf/2304.12244)
- can also finetune with RLHF or modify the Q-A pairs directly
- then you have a final model finetune once the Q-A pairs look good
- then you use RAG over the corpus and the Q-A pairs because the model doesn't remember all the facts
- then you have a bullshit detector to avoid hallucinations
So the corpus is very important, and the Q-A pairs are also important. I would say you've got to make the corpus by hand, or by very specific LLM prompts. And meanwhile you should be developing the Q-A pairs with LLMs as the project develops - this gives a good indication of what the LLM knows, what needs work, etc. When you have a good set of Q-A pairs you could probably publish it as a static website, save money on LLM generation costs if people don't need super-specific answers.
To add to the current top-scoring comment, though (https://news.ycombinator.com/item?id=42326324), one advantage of an LLM-based workflow is that the corpus is the single source of truth. It is true that good documentation repeats itself, but from a maintenance standpoint, changing all the occurrences of a fact, idea, etc. is hard work, whereas changing it once in the corpus and then regenerating all the QA pairs is straightforward.
I find the framework doesn't really speak to me (as a user, or prospective docs writer), and IME trying it out in communities I'm a part of, it didn't particularly improve the situation, as I had perhaps naively expected.
I get "reference" as a separate section, maybe, though to my mind the best docs are built around reference with explanations and little code samples and how-tos mixed in as necessary, and maybe a single "Getting Started" guide for installation and configuration and stuff like that.
-Tutorial/Quick start
-Reference (topic based)
-How-to guides (task based)
With an extra section:
-Expert tips (various things the product can do that aren't obvious or easy to discover)
It does mean that there is a certain amount of repetition between sections, but I don't think that is a big problem. You just have to be conscientious when updating things.
In my experience, the key thing about documentation is to write it as you are creating the product. Do not leave it all unti the end!
- https://hamilton.dagworks.io
It's not always the easiest to follow (we often have disagreements about whether something is a tutorial or a how-to), but it's a really valuable framing and I think our docs have gotten better because of it.
With time and care, those can be turned into tutorials and explanations. I use Obsidian to embed reference PDFs.
The end result is too hyperlinked for most to understand and the all-in-one outdated mega page in OneNote gets passed around instead much to my disappointment.
In short: it looks identical because it's substantially his work, that he did while employed there. In fact, he's the one giving the talk in the PyCon Australia video there.
I agree that the Divio site would be well-served by directing folks to/acknowledging the newer site (as the newer site does).
i find that the divio/diataxis 2x2 can be -too- complete, which is harmful for earlier stage, less mature open source projects, and also equal weights areas that nobody equal weights in real life.
my system takes inspiration from real docs and creates a progression based on project maturity, aka prioritizing just the important stuff at the early stages.
- *Level 0: Basic proof of concept*
- _Example audience: you/colleagues/hobbyists_
- One sentence description for github headline
- README with API docs - goal is to save yourself from looking at source code
- _Example audience: greenfield early adopters. Ok with missing documentation, they are here for the idea. can contribute code/docs_
- One paragraph description with more context - could be a sales pitch but also give an idea of when to use you
- Feature list/Project Goals
- Install + Config Instructions
- _Example audience: brownfield early adopters. Ok with bugs, they have some problem that isnt well addressed. Needs convincing._
- Comparison vs comparable libraries
- Problem Statement - what you solve, how the developer/end user is better off with your thing than handwritten. aka Why You Exist
- Basic Examples
- Live Demos
- _Example audience: early majority user. Wants ease of use, quick wins. Need to be very reliable. Needs content to sell solution to team_
- Project Status badges
- Tutorial
- Third Party Plugins/Libraries
- How-To Guide/Cookbook/Recipes
- User/Maintainer Content
- Official Blog/Project and Meeting Notes
- Talks
- 3rd Party Blogs
- Video Tutorials
- Podcasts
- Comprehensive Examples
- _Example audience: expert user. Needs API stability/migration instructions, deep insight on how the project works and how it can solve problems. Needs to customize/adapt for at-scale/weird usecases_
- Growing the MetaLanguage
- Origin Story/Naming
- Who Uses Us
- Logos
- Quotes/endorsements/testimonials
- Link to production use
- Funding
- Migration docs from previous versions
- Roadmap
- Reader-friendly Changelog
- Anti-Docs
- Helping Contributors
- _Example audience: Industry beginner. They may not know any alternatives. You are the entire world to them._
- Explain acronyms, jargon
- "1 to N" Docs
- Different docs for different audiences (eg JS/Android/iOS)
- Different languages
- Examples
- [Vue](https://vuejs.org/)
- [Django](https://docs.djangoproject.com/en/3.0/) - some [meta thoughts here](https://jacobian.org/2009/nov/10/what-to-write/)
- [React](https://reactjs.org)Like, three line basic how-to vs. one that shows how to (!) achieve something more complex, or not intuitively possible to perform with the tool being documented. Explanations that only tell you why you would not want to use the tool, sort of a laundry list of things that you can't or shouldn't be doing with it, and should be using something else, as opposed to a comprehensive look into how (or why) the tool works, and how it is better than competition, for example.
Not sure if that makes sense from a more systematic point of view, but it could easily help structure your documentation: "The Tutorial" and below it "list of additonal advanced and obscure mini-tutorials".
This is not to say anything about the length of each document, but naturally shallower ones could often be shorter.
FAQs and "Gotchas" need a "home box". So do gists. Maybe a third dimension would be something like "degree of curation" or "need for taxonomy and organisation" ?
FWIW... DITA has concepts, tasks, & references - and AFAICT these map fairly nicely to Diátaxis.