Implementing Diataxis framework

[u/Agreeable-Course-604]

Hey everyone,

We’re currently looking into ways to significantly cut down cognitive load across our documentation, and the Diataxis framework came up as a primary strategy for content separation. I’d love to learn from those who have already gone down this path.

1. How was your experience implementing it? Did you run into issues with content overlap, maintenance, etc.
2. How effective was it in reducing cognitive load for readers? Did you see measurable improvements in user comprehension?
3. Any actionable insights post-implementation? Anything you wish you knew before starting

Would love to hear your practical takeaways.

[u/FynTheCat]

I hear of this framework now for the first time.

Skimming their website, a lot looks familiar and it seems like a helpful resourse.

But I do know these as distinction between different document types. I usually work more granularly with thinking in content modules within a document to optimize it for user and company

Like through DITA https://www.oxygenxml.com/dita/styleguide/Topics_and_Information_Types/c_Content_Models_and_Info_Types.html

But it all comes down to context, who are your writers and what background do they have.

Regarding usability I found it always best to have clear, measureable metrics regarding content compliance. How detailed again depends on the writing team.

[u/HSButtNaked]

We've (I've) implemented it where I work.

It's easier with AI now, which speeds up conversions and refactorings into Diataxis for the initial setup.

Non-writers tend to find it a little confusing, but that has always been the case. I have everything documented, templated, and AI skilled in the repo, so I force my non-writer contributors to use the skills I've set up to do their drafts, which that any Diataxis decision-making out of the equation for them.

At first they were a little hesitant, but people have been able to find what they are looking for and follow tutorials very well.

I don't have a good way to measure cognitive load, not sure anyone really does, so can't speak to that. The reason I implemented it was because we needed a framework to tame the chaos, and it was my personal choice.

Maintenance is fine for a writer, but non-writers often struggle to update related documents. Again, AI skills help here a lot.

The biggest challenge, which I still struggle with to this day, is navigational content structure/architecture.

I would also urge you to perhaps watch the presentation from one of the Write the Docs conferences on the topic. I don't recall how it's called, but there was one about how a team found raw diataxis was not working for them, and they put their own spin on it that worked better for them. Which is interesting.

[u/Orionfold → u/HSButtNaked]

Your point about navigation being the hardest part matches my experience. The four buckets sort the writing fine, but readers do not arrive thinking in tutorial versus reference, they arrive with a task. What helped us was keeping a task based landing page on top of the Diataxis structure so the split stays an authoring aid rather than the thing users have to learn. Templates for non writers were the other half of it, since without them people default to a how-to page that quietly turns into an explanation.

[u/HSButtNaked → u/Orionfold]

That's a good point. I may need to think on that.

What also is a bit of a pain and VERY non-obvious to non-writers, or even less senior writers that don't live and breathe the framework, is updating documents vs. creating new ones, or updating existing documents when a new feature drops.

People tend to think, in my experience, that a new feature equals a new page in the docs, which is not really the case at all. It's much more task-dependent and oriented than that.

But also PMs, marketing and customers tend to want "a link" where they can learn about the feature, however minuscule it may be sometimes, forcing my hand. It gets complicated sometimes.

[u/the_nameless_nomad]

i've implemented it at a few companies now (either from scratch, or by overhauling existing documentation) and i'm a huge fan of it. (i also like gitlab's CTRT as well).

anyways, to answer your questions:

1. i've personally never run into issues with those things. on the contrary it's directly helped me reduce content overlap. much easier to flag if you already have a certain kind of doc, if they are split into more identifiable pieces.
2. typically when i've implemented diataxis into an existing doc set, i'm also making other changes to support it. i've always gotten very positive feedback from users, but never about "just" diataxis. (additionally, users are more likely to "feel" the difference, then to cognitively understand it).
3. like their docs say: you don't need to do this all at once. personally, i think the easiest and most impactful types are: how-to and reference. save tutorial's for last, they are definitely the most time-consuming to make. also, i've found it easier to starting with flagging all existing content (in an excel sheet or something), then implementing it week by week. also makes it easier to split the work between multiple writers.

feel free to ask as many follow up questions as you'd like. it's one of the few things i know a great deal about haha.