Diátaxis – A systematic approach to technical documentation authoring

Adoption and Real-World Use

• Many commenters say Diátaxis (or its earlier Divio version) is now de facto standard in tech-writing circles and in some orgs (e.g., Canonical/Ubuntu, Haskell community).
• Several teams report strong improvements after adopting it: clearer page purpose, easier maintenance, better user flow, especially when combined with page ownership and periodic reviews.
• Some tried to apply it internally and found culture (expediency, “just write a how‑to”) can limit its effectiveness.

Perceived Benefits

• Main value: a simple mental model that prevents “one giant doc that tries to do everything.”
• Helps authors keep modes separate (tutorial vs how-to vs reference vs explanation), which reduces muddled docs.
• Particularly helpful for non-writers and developers as “training wheels”; even imperfect adherence improves clarity.
• Good at framing user-focused goals: learning vs solving a problem vs looking something up vs understanding “why.”

Critiques and Limitations

• Several worry about dogmatic enforcement: forbidding any mixing, rejecting useful examples or brief explanations in tutorials, etc.
• Some users find the category names (tutorial/how‑to/explanation) too semantically close and confusing in navigation; need extra pages to explain the distinctions is seen by some as a smell.
• Concern that strict separation can hurt interlinking between quadrants and make exploration harder.
• Some writers feel real learning often benefits from blending modes and carefully chosen examples.

Terminology, Diagrams, and UX

• Debate over old Divio diagrams vs newer Diátaxis wording: some prefer the earlier, more concrete axis labels (“useful when studying/working,” “practical steps/theoretical knowledge”).
• Others see the Diátaxis site itself as verbose and harder to onboard people with compared to older one‑page explanations.

Relationship to Other Systems and Variants

• Parallels drawn to DITA topic types and “every page is page one,” but with different granularity and reuse goals.
• Alternative frameworks proposed (e.g., maturity/“documentation levels”) that prioritize different docs at different project stages.
• Some add extra “boxes” like FAQs, gotchas, expert tips, or language variants as pragmatic extensions.

Docs, Duplication, and LLMs

• Broad agreement that repeating information in multiple forms is often necessary; tension with keeping everything consistent and updated.
• A few speculate about writing with LLMs as the primary consumer of docs, but implications remain unclear.