I also admire what there isn't: certs, training, manifesto, "yah ain't holding it rite" blog posts, and job ads for a "Diátaxis Master".
Wait until it becomes popular.
Diátaxis
51–60 of 66 posts
Re: Diátaxis
#52Please do not make me click on "reference" to get to "API docs". I love diataxis, but dear lord, do not make me click an extra time to get to the thing I actually need 95% of the time. 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. Ple…
I'm genuinely confused about what one would expect under "reference" that isn't effectively API-shaped (in the context of software). Like, I've never consciously thought of this before but I can't remember a time that they haven't effectively been synonyms in my mind when I'm navigatig documentation.
That's part of the problem. Some projects, when they move to diataxis, will create a top level section called "reference" and have a single item under it called "API" (or similar.)
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.
Re: Diátaxis
#53I've also found these guidelines helpful: 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…
> 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.
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.
Re: Diátaxis
#54I love whenever this comes up. It’s a great framework for thinking about and writing docs. 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…
Something that Python gets right is that their entire docs site is versioned - select 2.7.18, for example, and you get the 2.7 docs right down to the tutorial. The Python development process is also very careful about keeping documentation up to date; the PEP process even requires an explicit "How to Teach This" section for proposals that add or change language features.
Re: Diátaxis
#55Re: Diátaxis
#56Earlier quoted context omitted.
I'm genuinely confused about what one would expect under "reference" that isn't effectively API-shaped (in the context of software). Like, I've never consciously thought of this before but I can't remember a time that they haven't effectively been synonyms in my mind when I'm navigatig documentation.
That's part of the problem. Some projects, when they move to diataxis, will create a top level section called "reference" and have a single item under it called "API" (or similar.) 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…
Oh like that. I was thinking of situations where "reference" just directly links to the API keyword index, e.g. the P5 docs[0], putting a redundant extra page between that would annoy me too.
Re: Diátaxis
#57Re: Diátaxis
#58How is this different from Divio's documentation system?: https://docs.divio.com/documentation-system/ Update: https://diataxis.fr/colophon/#origins-and-development (Divio came first).
But when it comes to diagram, I still refer to the Divio version as Diataxis version description is too abstract.
Re: Diátaxis
#59The concept of 4 different uses of documentation seems great. But I wonder why the presentation of Diaraxis itself is not clearly structured into these 4 different "views" on documentation? Or are they?
Look at the left menu. There isn't a reference, because the concept really doesn't need a reference. All the others are there.
Re: Diátaxis
#60It seems like a typical french IT project: I have never heard about it, it looks very nice, but I can't quite figure out what kind of problem it solves.