Diátaxis
diataxis.fr
diataxis.fr
Diataxis was fantastic. It took a bit of effort to work out what the page titles were to cover everything we needed, but then when you were writing a page it was glorious.
It was so clear what you were saying and what "voice" you were writing in. If it's a Reference page you're all descriptive, with diagrams and bullet points. When it's a guide you're more discursive, but you know you're just imparting information not trying to teach. It made it so much easier to be coherent and clear about everything.
If you're embarking upon a refactoring / rewriting journey for your docs, the only advice I'd share is to actually read the website beginning to end before starting. Especially this page: https://diataxis.fr/complex-hierarchies/. The guide is (unsurprisingly) very well written, and it's easy to internalize the concepts because they're repeated often.
There is a real problem there, and that page doesn't do a good enough job of dealing with it. I have something cooking that is much, much better.
The docs I have built up are at times too technical for users and not detailed enough for developers. I am not sure if it's a skill issue on my part for an individual piece of text, a skill issue on my part in applying the principles outlined by Diataxis, or a fault in the framework itself (or its self-documentation).
Huh. The “Start here” page says exactly the opposite. It's literally the first two sentences on the page:
> You don’t need to read everything on this website to make sense of Diátaxis, or to start using it in practice. In fact I recommend that you don’t.
So what makes you recommend reading it all first?
https://github.com/WillAdams/gcodepreview
In particular, it made it seem obvious to split up the documentation between:
- Overview --- readme.md
- Tutorials --- handled in various template files
- How to Guides --- embedded in the Literate Program code
- Reference --- the indices and Command Glossary
Huge fan of Diataxis over the years!
It’s hard to keep documentation up to date, however, and I find that items like tutorials and reference materials (unless generated off versioned code) can drift pretty far over time.
A feature I like in concept that notion introduced with wikis ages ago was a “verification” timestamp, where you specify a timeframe after which the doc owner has to reconfirm that the doc is up to date. A bit too easy to rubber stamp, unfortunately, but maybe if it took the doc offline entirely without a more robust audit.
- Tutorials are implemented as "vignettes", executed on package validation - How-Tos are attached in roxygen documentation chunks, likewise executable by default - execution disabled when expensive or to avoid side effects. - Reference is implemented in a TeX or Markdown format, commonly parsed by roxygen
The only thing that's missing is a canonical way of documenting implementation rationale. Having the documentation outside the repo worked before LLMs, but there was always that weak point of code drifting away from the documentation...
Python has pretty good autogenerated reference docs, but if you want more than markdownified docstrings it makes them as difficult to maintain as the other pillars. As a set, the pillars aren’t as neatly grouped in Python documentation tooling, but I typically differentiate how-to, tutorial, etc with type tags in Notion or other indexes that point to where each type of thing lives.
1. In general, do whatever Wikipedia does. e.g., start with a one-sentence definition, then a couple paragraphs of summary, then go into short specified sections, and keep links to the "Citations" at the end. It's been refined for 25 years, it's older than most of your engineers, it's 50+% correct by default.
2. Keep every section to one screenful. If your reader can't see a headline, they get lost.
3. Put a funny picture at the top of the page. Or at least something off Wikimedia Commons.
4. Don't spend a lot of time writing anything. And don't use AI. The AI doesn't know what's inside your head. You yourself have an inkling. The longer you write, the further you'll get. Just write one short thing at a time and refactor aggressively later. Never throw shit over a fence blind. Nobody reads shit that's been flung over a fence.
Steven King said writing is telepathy. All mediated communication sits on a Pareto trade-off with face-to-face communication. Media is always less interactive with slower iterations. You need to figure out exactly what your audience needs, right when they're reading, and write just that, knock 'em dead, and leave. Don't add detail. They'll ask if they need detail.
I went to a documentation workshop at Pycon UK by Daniele, and this was actually quite similar to his approach for writing front pages for documentation. He'd give the same questionnaire to a few teams, with prompts like "in one sentence, what is this product?", "What can a user accomplish with this product?", "Who are the primary users of this product?" Once everyone's aligned on answers, the page writes itself.
Update: https://diataxis.fr/colophon/#origins-and-development (Divio came first).
Just released, alpha quality, need feedback/fine-tuning. Testing it now on my OSS repos.
Parataxis: arranging alongside
Diátaxis: arranging across
It feels so natural and obvious compared to Diataxis' forced abstractions, where I'm still left wondering "what's the difference between a tutorial and a how-to guide?"
But! I'm glad for anything that helps people organize and maintain docs.
I don't find this question difficult. Without looking anything up, a tutorial exercises a contrived example for learning purposes, whereas a how-to guide provides instructions suitable for real world execution.
Example in our codebase
- How to clear the cache ?
- How to configure the logger ?
I liked the idea of separating our how to guides and explanations / tutorials, because sometimes you just want engineers to follow a specific flow without going too much in depth.
There are repetitive bloated texts with unnecessary distractions and unenlightening illustrations. It is maybe well-organized, if one can speak about good organization of poorly expressed knowledge at all.
Really curious what the major differences are that have you preferring it over other methods / winging it.
[1]: https://c4model.com/
I read a lot of cookbooks, and interestingly enough, I never stopped thinking about what makes a good cookbook (except for its recipes). Diataxis answers that in a way. Indeed, the best cookbooks I have read in some way or another followed Diataxis.
Overall, the movement is good, except for how it tends to turn 1-click docs into 2-click docs (or more for folks who don't know that API docs probably live under reference.)
You are allowed to have a top level tab/link to API docs. Please do not hide those from me while you "improve" your docs.
A lookup table of normative specifications of CLI arguments would also be Reference.
So they are not synonymous.
To be clear, I'm not advocating for navigation that must always have this structure in cases where it's redundant. I think people should do what makes sense. But I think it is nevertheless useful to not mix the different categories.
Depending on the docs theme, it can require clicking through to get to it.
It is a minor annoyance.
edit: Also gonna tack onto this that my original comment reads way more acerbic than I actually feel. I was sleepy and didn't proofread for tone like I normally do.
tutorial/setup-buh-snuh-env.md
how-to/configure-buh.md
install-snuh.md
reference/buh.md
snuh.md
snuh-licenses.md
explanation/why-we-use-buh.md