Diátaxis – A systematic approach to technical documentation authoring | Hacker News Reader

Diátaxis – A systematic approach to technical documentation authoring

diataxis.fr

514 pointsOuterVale113 comments

As a non writer I found that even without the details there's just one very important and very basic insight here:

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!

There is even a lot of potential for communicating more effectively here:

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

Giving a few good examples also has the benefit of demonstrating the author's own understanding. If the author can't describe the matter in different ways, it shows don't have a feel for "it", and they're not grasping it rightly or even touching it at all. I've found that audiences can sense when a speaker is out-of-touch, and will politely ignore them.

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.

And two of them should be the most obvious example you can think of, and the weirdest example you can think of.

I have a friend who's a pastor. As a basic rule of a good sermon he always quoted the old addage: "Tell them what you’re going to tell them, tell them and tell them what you’ve told them".

There's more art to it, because there's also an off-putting way of doing that, which frequently shows up in presentations: you're greeted with a powerpoint slide with the topics in bullet points, which the presenter reads out loud, then come the slides with each of those points, also read out loud, and at the end there's a summary that almost copies the first slides, and which --for good measure-- is also read out loud. That makes me want to forget everything that's been told.

It's an incredibly common mistake, for the presenter to put up slide after slide that is just a script of what they want to say - then your brain has to choose between listening or reading, to the detriment of both.

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 best presentation I ever saw was done by a colleague of Mikel Harry's at a Six Sigma conference in Frankfurt. The presenter had no ready made slides but he had an overhead projector, three transparencies, a handful of dry marker pens, and an eraser. As he spoke he sketched charts and diagrams to illustrate his points. If an audience member asked a question he was able to provide an answer in both words and with another sketch.

The old ways are the best.

Reminds me of Presentation Zen or the 10/20/30 rule which states that “a presentation should have ten slides, last no more than twenty minutes, and contain no font smaller than thirty points.”

The anecdote doesn't strike me because your friend the pastor said it, but because it's a rule as old as times that every high-schooler was taught.

- 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 every high schooler, TedX speaker, and Malcom Gladwell impersonator gets this wrong: It only works if intro and conclusion present a different view on the information, otherwise it's simply boring the audience to death.

Then the challenge becomes recording where each thing is recorded so that when it needs to be updated, you update it everywhere and don't end up with conflicting documentation.

This. Repeating information is helpful. repeated information that became inaccurate isn't. It's a difficult line to balance

Someone will trip on the mistake and report the bug and you fix it.

You dont get a compile error if the documentation is wrong. Chances are you wont notice.

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.

And by then you have several people on the team who have thought the wrong way is the right way for months, never mind your support team probably giving end users bad information.

It's messy.

True, even when you are writing a scientific publication with a hard page limits (~8 pages), it is advisable to reiterate the core messages multiple times as you add more context and details:

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

expanding this take perhaps too much

...even the source code itself "says", in its own way, the same thing as the documentation, just to a different "audience" (the compilers)

We just applied this framework to the Sequin [1] docs two weeks ago. It has felt so nice to have a framework. I think our docs flow really well now, and it's been easier for us to add and maintain docs because we know where to put things.

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 :)

I checked out your docs, and I agree that they flow very nicely! So often it seems that docs are either frustratingly vague to the point where it almost seems like the company is embarrassed to admit that their tool is a tool and not a "transformative synergy experience" (or similar nonsense), or docs immediately get overly specific without covering "why this product exists".

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)

Aye, thanks! That's very helpful to hear. I just cut back our use of the acronym a ton:

https://github.com/sequinstream/sequin/commit/28bfba603da6d2...

In case you weren't already aware, most markdown parsers support actual HTML tags in it, and there's <abbr title="change data capture">CDC</abbr> that allows being visually succinct, is a11y friendly, and in most browsers is visually distinct to prompt the user there's more content hidden in the hover or long-press

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

Very fun – I wasn't aware, thank you!

You were _this_ close!

What’s a CDC?

I think having those four approaches is the key thing and you’re addressing it well. The flow is really the readers choice. My brain works in the way of wanting the overall explanation first. Then I seek the how-tos and tutorials.

This analogy is really good, now I totally see the benefit of this framework.

I'm a technical writer. Diátaxis is similar to DITA: https://www.oxygenxml.com/dita/1.3/specs/archSpec/base/infor...

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

>Diátaxis is similar to DITA

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.

Got an opinion on LwDITA ? Or are you deep enough into DITA that the complexity is not an issue ?

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.

The trouble with DITA is that it is very often accompanied by its own very opinionated toolchain, although of course it's not mandatory. There are better ways to write docs nowadays than wrestle with XSL/FO and its brethren.

It's very popular in tech writing circles and pretty standard now as others have suggested.

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 these four categories on their docs page

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.

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

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.

> We do see people try to take it too far though

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.

Eh, I've found that doc pages that try to establish really hard lines will still fail, and end up at a high level of quality. I think of it like a programming principle in the "don't mutate global variables" or "write shorter functions" category: you don't have to get it completely right, but most people really would be better off moving more in that direction rather than away from it.

The approach works better with dedicated technical writers. It makes sense to have distinct user-focused goals for documents before they’re written, and then just dig into the necessary parts of the software enough to make that happen as needed. When it’s developers doing the docs, they’re approaching it from the other end. They’ve got a chunk of code they need to cover, and reasoning about user needs is pretty difficult from that vantage point. Picking an approach vector when you don’t know the airport.

I think that's a SHOULD in the send of RFC 2119: "There may exist valid reasons in particular circumstances to ignore a particular item, but the full implications must be understood and carefully weighed before choosing a different course."

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

I recently saw someone praising the scikit-learn documentation, mentioning this page specifically https://scikit-learn.org/1.5/modules/grid_search.html so I took the top section and asked Claude to classify it with this framework:

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

Interesting use of an LLM to help us write better and more organized documentation. What prompt did you use? What are your thoughts on the outcome?

Having just completed my first (and last, for a while) shipping SwiftUI app, I very much think that documentation has been treated in shabby fashion, in the modern tech scene. I sorely miss the work done by all those great tech writers that Apple fired. Their engineers are terrible documenters.

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 don't think of diataxis as a dogmatic approach, but rather a pragmatic one. You can dive pretty deep into the weeds in how to structure your documentation, but this is a very good training wheels until you find places that leak.

I agree, but I guarantee that it will become dogma.

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.

> Many good ideas have been destroyed by too-rigid applications

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.

Well, what I mean, is that folks invest in the dogma, to the point where they refuse to accept any changes to fit realities, and often believe that they can apply the dogma, in areas, or in a manner, where it is not appropriate.

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.

Diátaxis is a great way to structure documentation, but I think its real value is in simplifying how we think about writing docs.

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.

Isn't the documentation task highly dependent on the goal and prospective users. Or is there a unified paradigm?

We use it at our organisation and ever since we adopted it, our technical documentation is on a whole other level. That, page ownership and periodic reviews of each page by one of the page owners has made our technical documentation the only successful documentation effort that I've seen

I think the graphic used by divio[1] ist so much more intuitive. But seems Diátaxis has more comprehensive documentation on what they mean.

1: https://docs.divio.com/documentation-system/

https://diataxis.fr/colophon/#origins-and-development

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.

Why do you think the version on the Divio site is better - what's more intuitive about it?

Not the GP, but I agree:

• “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.

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

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.

It's the same "useful when we're learning" vs "useful when we're working" dichotomy, isn't it? :) When I want to tell someone about the idea of organizing their documentation into four buckets — or really, just about being conscious about the goals / the intended audience and usage — I really just want to plant a seed to have them open to the idea, i.e. at this point it's “Theoretical knowledge” rather than “Practical steps”. Later if they are persuaded they can go to diataxis.fr and learn more / get the “useful when we’re working” / “application” tools.

[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.]

I can see your attempts to generalize, i.e.

  Acquisition := Most useful when we're studying
  Application := Most useful when we're working
  Cognition := Theoretical knowledge
  Action := Practical steps

...but in my mind, the older quadrant labels were immediately insightful at a glance.

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

Not GP but thought of the exact thing when seeing this - look at the wording on the axes.

I like the idea of this (and have been lucky enough to meet the creator a couple of times at PyconUK - he's a talented and very friendly chap), but I have a reservation about being this rigid about differentiating between the various areas of documentation in this way.

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.

I don't agree with it because while I think that it's theoretically correct, the words are too close together. To me "tutorial", "how to guide" and "explanation" are all practically synonyms. I know that when you think deeply about it, there are legitimate reasons for each category but it's just too close semantically that my brain can't see the difference. If I want to know how something works and I see "tutorial" and "how to guide" I have no idea what to click and I just click on the first thing.

>the words are too close together. To me "tutorial", "how to guide" and "explanation" are all practically synonyms.

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

Can you see the problem though: If you need a huge page dedicated to explaining the difference between how-tos and tutorials then it's clearly too confusing and not obvious at all. Nobody is going to need a page telling them the difference between sample code and documentation. Those two words are obvious even though yes, sample code is of course also documentation in a sense.

It all seems close because the terms are muddied in our minds by countless poor instructions over the years.

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

But I want to learn something in all of those examples. I have a goal in all I do. I need technical information in all as well and I want to gain understanding in all of those as well. It really is just a bad way to name these categories. I haven't thought about how to do it better yet, I personally like the ziglang docs where everything is presented as a huge reference document with examples in each section. The only additional thing that is needed is usually something like APIs and executable code. Of course the reference document can also have executable samples like what Stripe does. But somehow I think a dedicated section for example code is legitimate in addition to a long reference.

I think they wanted to separate out four different concepts in the territory, needed a name for each one, and so picked four almost-synonyms for the labels on the map. We can read "tutorial" in their system as a technical term rather than its everyday meaning, just as "depression" has a particular meaning to a psychologist that might not match everyday use.

I guess that's still better than labelling them Type I-IV tutorials.

Are they really so close?

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.

Your videogame example shows the problem. Tutorials are effectively just a different form of walkthrough. You are getting walked through the basics. So that's my point, you can't have different words on your website that is supposed to help people gain understanding and then start off by confusing everyone with words that are all so close in meaning.

The purpose is always the same: To learn. It's how you learn and what your learn for that are different. A tutorial is for getting exposed to something. A guide is for a very specific purpose in something you're already familiar with. An explanation is for a deeper understanding and references are for not relying on memory. They all refer to different things that ultimately falls under the same concept (and intersect with each other). If you're building a system, you should have all of them otherwise, the documentation is lacking.

> "tutorials are just a different form of walkthrough"

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

You also need good writers who by example make it perfectly clear what's what.

how-to is for configurations. tutorial is for orientation. explanation is for models.

I'm a big fan of Diátaxis and I'm using it to build documentation for Logdy: https://logdy.dev/docs/quick-start I'm curious how people see it and whether it's a useful way to document a software product, feel free to leave a comment. So far it proved to be an effective way to communicate how to use the product also through a series of blog posts that present common use cases. Defininitely recommend!

I don't know if it's perfect, but I have yet to meet anything better. I discovered it late in my 20-year technical writing career, and it felt like meeting an old friend for the first time.

As a technical writer, I had been groping my way toward a framework like this myself and this is great. It is great because it gives a simple framework to work with that most people can understand very quickly and the graphic is amazing for referencing.

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.

I often get stuck changing from reference to explanation in the middle of wirintg, so this is a great guide. Having a small How-To example in every reference entry for a API endpoint might be good, but you need to keep them seperate and concise, do not start with explanations.

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

Examples in reference material are an excellent idea, and not at all in contradiction to the principles of Diátaxis. An example illustrates - like an illustration in any other reference guide - and provides something concrete to help grasp what's being described.

That's different from a how-to, talking someone through a problem.

Golang API pages collect all examples into a list at the top. Maybe do the same kind of things for stuff like "Quick explanations" and "Warnings/Gotchas". But it would get very subjective and potentially very messy and unmaintainable.

The Haskell language's documentation team officially recommends using it: https://blog.haskell.org/documentation-best-practices-in-202...

I feel like I should be writing with the goal that the end reader is actually an LLM. The LLM will be the one spitting out the answers to the actual users via things like co-pilot, but I am not sure how that should change my approach to structure or level of detail in docs. Heavier on the number of code examples?

Well, look at the process of training a chatbot:

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

Ask an LLM to write it?

Does anyone have examples of OSS projects using this framework, and having good documentation?

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.

All of Canonical's documentation is written with Diataxis. Here are the Ubuntu Server docs: https://ubuntu.com/server/docs

Ooooh! I've seen this organization before, but didn't realize it was a thing, or had a name. I don't personally like it, as I get confused about where to go. When I saw "tutorials" and "how-to guides", for example, I had thought those were roughly the same thing and didn't know which to click. And seeing "Explanation" separately was even worse because why would I want a guide or tutorial without explanations??

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.

I recently built a small, free analysis tool that takes public documentation git repos and evaluates the content against this framework:

https://app.getdocsy.com/analysis/

I arrived at a similar approach for my product documentation, with main sections:

-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!

We've leveraged Diataxis heavily for Hamilton and Burr documentation:

- https://hamilton.dagworks.io

- https://burr.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.

My experience trying to implement this for internal use in a tech-adjacent industry is that "how-to" guides dominate because of a company culture of expediency over quality.

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.

I use and highly recommend this framework as the starting point for any technical documentation. It helped me learn how to keep the detailed technical explanations out of the how-to documents. Before I learned of Diataxis, my how-to docs were much longer and hard to follow when things go right (because I had lots of, "if this doesn't work, investigate A, B, C...").

The ideas presented are great, and I can see myself adopting them in the future. However, the tone of the accompanying text feels off-putting, which makes me hesitant to share it. I hope this aspect improves over time

We have been implementing Diátaxis style engineering documentation. We have "librarians" that make sure information is going to the place, and that we aren't creating unnecessary duplication.

How is this related to https://docs.divio.com/documentation-system/ ? Looks incredibly identical.

This was discussed in the thread a couple days ago about board game rulebook design. I had a similar question (https://news.ycombinator.com/item?id=42302038 - although I phrased it more like wondering if Procida had been ripped off) and got some insightful replies.

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.

Thank you.

Explained in https://diataxis.fr/colophon/#origins-and-development. No malfeasance! But I wish Divio would take that down, it's past its sell-by date now, and I think I got quite a few things in it wrong.

I actually find the contrasting approaches (see discussion elsethread about the terminology used in the diagram) helpful and it's always good to have historical context.

I agree that the Divio site would be well-served by directing folks to/acknowledging the newer site (as the newer site does).

Same guy

So does it track the users-role and reading path + searches? Like, if you searched for topic "XY" hop on rail XYZ other user with similar role hoped on.

I’ve read about this approach in the past and am curious if anyone has any experience trying to get an organization to buy into it.

Yup, just do it! Whenever I write a new piece of docs I try to fit it into one of four categories. Whenever I find docs written by someone else and they're all over the place, I message them and say "Hey this would be much more useful as a how-to" and link to this site.

I think this idea is so common now that it is almost the standard for technical documentation at this point even if people don’t know it by that name.

here is my alternative system: https://www.swyx.io/documentation-levels

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

- *Level 1: v0.x*

  - _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

- *Level 2: v1*

  - _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

- *Level 3: vX*

  - _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

- *Level 4: Production use for multiple years*

  - _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)

Where would ChatGPT fit?

It can, on a good day, produce several kinds of documentation if you describe what you want.

Yeah LLMs ingest all 4 and can conversationally give you all 4. I suppose it’s orthogonal.

A frequent post to HN. It seems there is appeal in trying to systematize the entire idea of TC. I'd like to see this extended to three dimensions.

A natural third dimension is language. If your user base is very international, you might need most of these documents in multiple languages.

User interface language is orthogonal to ebberyting.

and I'll upvote it every time it comes up.

For every dimension you add, you double the amount of docs you have to write.

You double the number of document types. But if it helps, it helps.

What third dimension would you add?

Depth?

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.

Fair question. I've read a couple of critiques of Diátaxis that suggest additional boxes.

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.

FAQ lists are the equivalent of the box in my garage where I put things when I've been told to get them out of the house, and I can't actually be bothered to put them in the right place.

Reply on news.ycombinator.com