We fixed our documentation with the Diátaxis framework
blog.sequinstream.comHey, nice work. I think dedicating time and effort to documentation pays off in years to come.
Also -- from your original plug about your product I would have ignored it, but after reading through some of the docs, I actually see some use cases for this in a couple of upcoming projects!
What I'm about to say is a big topic that's probably better suited as a blog post, but I'll try anyways.
I think Diataxis is a valuable aid for thinking about documentation strategy but is not always necessarily a literal blueprint. I.e. when determining whether you have completely documented an area, it's very valuable to ask yourself "do we have tutorial content for this area? Explanations? References? Guides?" but it doesn't necessarily mean that the tutorial and explanations need to literally be on different pages.
We tried adopting Diataxis on pigweed.dev [1] as a literal blueprint and it resulted in too much fragmentation. E.g. the explanations for a Pigweed module were on one page, but the tutorial was on another. Users and teammates found it annoying to have to jump back-and-forth so much. In my mind, I still use Diataxis as an internal checklist of sorts, but I don't necessarily require the content to be split across different pages. E.g. sometimes the most natural/effective place to put an explanation is in a tutorial, when the user is getting hands-on experience with that topic. You reinforce the theoretical foundations with the direct experience and vice versa. If you only link to explanations from the tutorial, some (most?) users won't click those links, and therefore may never get exposed to the theoretical foundations. For some areas that's OK; for others it's could be a disservice to the user. It depends strongly on what you're documenting.
I believe I have discussed this with Daniele on the Diataxis channel in Write The Docs Slack [2] and they responded that this is why they call it modes of documentation.
That said, these recently updated docs [3] reflect our general approach to Pigweed module documentation [4]. You can see that we still do often split our docs clearly along the lines of references/guides/explanations/tutorials.
The other big limitation of Diataxis IMO is that I'm not sure if the map [5] really is a comprehensive way to think about documentation. (As I've said in previous HN discussions about Diataxis) How do homepages and READMEs fit into the map, for example?
That said, the world's documentation is much better off thanks to Diataxis. The fact that it gets discussed a few times every year here on HN is a great service because it makes the task of improving documentation much less daunting and much more straightforward, and provides very focused discussion on how to improve documentation strategy in general.
Update: I think [6] is a newer document (published Aug 2023) that has been added to cover the complexities I mentioned in this comment. This page was not on my radar.
[1] https://pigweed.dev/seed/0102.html
[2] https://app.slack.com/client/T0299N2DL/C02149LN2HJ
[3] https://pigweed.dev/pw_rpc/ for on example, https://pigweed.dev/pw_async2/ for another
[4] I'm well aware that some docs on the site are in bad need of an update, so please don't grab some random page from the site and tell me that the pigweed.dev docs suck and therefore everything I say is invalid
Diataxis is a great way of thinking about documentation and it really helps organizations get documentation off of the ground.
I generally didn't make separate pages for each type of documentation, they were separate sections.
For example, for a particular feature I would have an explanation at the top so someone looking at it would know what it was for, the audience would be a prospective customer/user trying to determine if they want/need to use it to do a task.
A tutorial section for someone who's never used it before, so very detailed.
A How-to section that has a easy to skim format so if someone is doing something but they can't remember all the steps they can go through it really quick to do the task so they can continue with their work.
The reference section would call out all the options and variables and prerequisites and so on.
For on-prem software the whole install and config section was a tutorial by default because they'd never done it before. A README should have two sections an explanation (what is it and what do you use it for) and a tutorial (how to set it up).
Tutorials are often in a separate section because people expect that but tutorials have an audience that have no experience in the product, the big problem is that the writer often has the curse of knowledge and has a hard time remembering what other people don't know and making sure to add that information in. They need to set up the framework to understand the design philosophy of the product so they can understand the How-tos.
Yes, we also mostly landed on a section approach (tutorial in one section, explanation in another, etc.) versus page approach (tutorial on one page, explanation on another page, etc.). Perhaps the Diataxis site itself should provide guidance on when you might be better off with a section approach versus a page approach, or some other approach entirely. The idea of modes is very subtle. I don't think most Diataxis readers immediately grok it. I think many people assume that the site is recommending a page approach.
What I'm hinting at re: homepages and READMEs is that there's an art and science to index pages (I think of both READMEs and homepages as types of index pages). I'm not convinced that you can boil down index pages to just a mix of explanations, tutorials, references, and guides. I think it's a different type of content that's not really well-represented on the Diataxis map.
a structured approach is better than a thoughtless one. and many teams approach documentation from a very haphazard and ad hoc sort of place.
Definitely, especially since the task of "improving the docs" can feel so daunting and ambiguous.
Related:
Diátaxis – A systematic approach to technical documentation authoring
I always want to jump right to the explanation documentation. The rest of it seems like a waste of time (well, the Reference bit can be somewhat useful later). I find tutorials and HOWTOs as misleading at best.
Well, that's your preference, it's definitely not everyone's. But you too would benefit from the explanation documentation being clearly labelled as such, so you can go there and avoid tutorials.
In hindsight, I realize my tone was off in that comment. I didn't mean it like it was the right choice or that there was anything wrong with Diátaxis. Since people find it helpful I presumed it was... and you're absolutely right about the clear labeling! This article was a really helpful insight for me.
I just hadn't really appreciated why other people wanted different kinds of documentation. I always feel like if I don't understand the "why" I really don't know the tool and therefore shouldn't use it until that was addressed.
> I always feel like if I don't understand the "why" I really don't know the tool
What I find for me, and what I think is really common, is that a longwinded "why" is not the right place to start - it's too dry, not practical, and I can bounce off it without understanding.
Starting with a demo, a "you can use this tool to do xyx in 5 lines of code, here's how" makes me see that it has value, to get a basic feel for it. And once that is in place I get that it has value - it's like a hook to hang the "explanation" on.
Then the reference is useful later, when you're somewhat familiar, but need to check a specific thing that you don't know yet. You don't need or want to read a long multi-paragraph explanation to confirm a technical "yes or no" question.
Yeah, if I'm reading documentation to decide if there's a value proposition worth exploring, I've already made a mistake. You've got a make the value proposition, and then I'll read about the "why" to understand if that value proposition can be realized. Why would I read a tutorial or a HOWTO for something with no known value?
The reference is relevant to me too, though modern information retrieval tools make it much less so, as I can often get the reference information I want in context. The main reason the reference is helpful is that explanations often aren't as precise as you need them to be about the specifications for the tool.
In retrospect, I do get some value out of tutorials & HOWTOs, mostly as a check on my understanding. They're just not where I want to start.
I think a good way of framing it is that a lot of documentation these days starts with "getting started", and I've observed that more often than not, that actually makes everything more difficult. If I understand the tool first, I avoid going down a lot of blind alleys and misinterpretations. I have observed that people often use a tutorial or a HOWTO as a way to get something done quickly without ever reaching that understanding, but the reality is the understanding is reason you wanted a human using the tool in the first place.
I guess they all have their value - e.g, imagine you just want to achieve a goal, then a turorial is exactly what you need.
If I'm in a rush to achieve a goal, using a new tool is going to slow me down, with or without a tutorial. I consequently find the tutorial of limited value and usually just something I scan through until I get to the "real" documentation. It's revelatory how this works for other people. I guess I always understood that, but didn't really "grok" it until now.
And tutorials give you an overview of how simple/complex something is to achieve, which may be just what you need before deciding to spend more time on the rest of the documentation.
If the “Hello World” tutorial for a new language takes 3 hours and downloading 15 GBs of files before you can start, maybe you’ll look at something else.