{"id":741,"date":"2026-03-13T22:40:36","date_gmt":"2026-03-13T22:40:36","guid":{"rendered":"https:\/\/www.matthew-morris.com\/wp2\/?p=741"},"modified":"2026-04-25T23:16:57","modified_gmt":"2026-04-25T23:16:57","slug":"diataxis-and-llm-assisted-documentation","status":"publish","type":"post","link":"https:\/\/www.matthew-morris.com\/wp2\/uncategorized\/diataxis-and-llm-assisted-documentation\/","title":{"rendered":"Di\u00e1taxis and LLM-assisted documentation"},"content":{"rendered":"\n

why should i even, i could be watching that pink flamingoes movie<\/strong><\/p>\n\n\n\n

I absolutely <\/strong>would not want to get in the way of you doing that: In 1989 I missed an all-night session of John Walters movies at the Scala in King’s Cross and I am still<\/em> full of pointless, futile regret. Don’t make my mistake. Go, with my blessing.<\/p>\n\n\n\n

ok i’m back now<\/strong><\/p>\n\n\n\n

Did you enjoy it?<\/p>\n\n\n\n

yes<\/strong><\/p>\n\n\n\n

I am so glad to hear that! Although it’s not a surprise, because everyone<\/strong> enjoys Pink Flamingoes.<\/p>\n\n\n\n

And, similarly, everyone <\/strong>is quite spectacularly confused about what documentation should look like in a world where obedient LLM servants are churning out text on demand. In particular: which bits should people still do, and what should be left to the machines?<\/p>\n\n\n\n

i too am confused about this. can you enlighten me?<\/strong><\/p>\n\n\n\n

I’ll do my best! But this will involve me inflicting some concepts on you.<\/p>\n\n\n\n

what concepts will you be inflicting upon me?<\/strong><\/p>\n\n\n\n

It’ll be all about Diataxis<\/strong>, which is a classification of documentation into 4 types. You can see a definition here: https:\/\/diataxis.fr\/<\/a> . It’s not a very<\/em> new idea – evolving from maybe 2014 onwards. It’s gained a fair bit of popularity already, but I reckon that the advent of LLMs will boost it further. Why? Because, on the LLMs-and-documentation front, it can help us decide what we should leave to LLMs, and what we should still put the effort in on working out for ourselves.<\/p>\n\n\n\n

why will knowing about Diataxis help me?<\/strong><\/p>\n\n\n\n

Diataxis helps us answer a crucial question for LLMs: how important is the viewpoint of the human reader?<\/em><\/p>\n\n\n\n

This matters because LLMs don’t understand people. LLMs are great if the identity of the human reading the documentation doesn’t matter. But if the human viewpoint is relevant, AI output will probably come across as alienating slop.<\/p>\n\n\n\n

so what, exactly, is diataxis?<\/strong><\/p>\n\n\n\n

Diataxis splits documentation across two axes: (1) acquiring knowledge vs applying knowledge (2) thinking about things (cognition) vs doing things (action).<\/p>\n\n\n\n

This results in the following 4 categories:<\/p>\n\n\n\n