HN Debrief

Diátaxis

  • Documentation
  • Developer Tools
  • AI

Diátaxis is a documentation framework that sorts content into four distinct jobs: teaching through tutorials, solving real tasks with how-to guides, describing facts in reference material, and giving broader explanation. The site lays out the method as a way to stop technical docs from mixing voices and purposes on the same page, which is a common reason docs feel muddled even when they contain the right facts.

If your docs have grown into a grab bag of readmes, setup notes, and API pages, Diátaxis is worth trying as a cleanup framework and as a prompt for AI-generated first drafts. Use it to force each page to have a single job, but expect edge cases and avoid reorganizing everything before you understand where the model is fuzzy for your product.

Discussion mood

Mostly positive and practical. People who had used Diátaxis described it as a real improvement for rewriting docs and for getting cleaner AI-generated drafts. The reservations were about rigidity, fuzzy category boundaries, and whether other models better match how users actually approach documentation.

Key insights

  1. 01

    Single-purpose pages sharpen the writing

    Treating every page as one documentation type forces a clearer voice and structure. That turns a messy handover document into something easier to title, easier to draft, and easier for a reader to navigate because descriptive reference, instructional guides, and teaching content stop bleeding into each other.

    Audit your docs page by page and ask what job each one is really doing. If a page is mixing teaching, task steps, and factual reference, split it before you rewrite the prose.

      Attribution:
    • rkangel #1
  2. 02

    LLM prompts benefit from the framework

    Using Diátaxis as a prompt template gives language models a much better target than "write docs". People reported getting decent first-pass output because the model can anchor on a concrete doc type and adopt the right level of instruction or description instead of producing generic mush.

    When generating docs with AI, specify the Diátaxis category in the prompt and ask for one page per category. You will get drafts that are easier to review and less likely to mix onboarding, operations, and reference into one blob.

      Attribution:
    • conradludgate #1
    • c0rruptbytes #1
    • radicalriddler #1
    • nchmy #1
  3. 03

    The tricky part is hierarchy

    The hard problem is not the four buckets themselves. It is how they map onto real documentation trees and product surfaces. One commenter warned that the site's page on complex hierarchies was important during a doc restructure, and the author replied that it was not good enough and was being replaced. That is a sign the framework still has unresolved guidance where teams usually get stuck.

    Do not start a large doc migration with just the four-category slogan. Prototype the navigation and section hierarchy on a small slice first, because the organizational edge cases are where teams burn time.

      Attribution:
    • jamilbk #1
    • DanieleProcida #1
    • LoganDark #1

Against the grain

  1. 01

    User-intent models may fit better

    A competing framework called the seven action model organizes documentation around what the reader is trying to do, such as appraise, explore, practice, or troubleshoot. That critique lands because Diátaxis can feel abstract when categories blur. The tutorial versus how-to split is intuitive to some readers, but not to everyone, which suggests the model's elegance does not guarantee it matches user behavior.

    If your audience journeys are more important than your content taxonomy, test a user-intent structure before committing to a full Diátaxis rewrite. Navigation based on tasks and lifecycle stages may outperform a cleaner theory.

      Attribution:
    • wonger_ #1
    • rlpb #1

In plain english

cargo-culting ↩
Copying a process or practice by imitation without understanding why it works or whether it fits the situation.
Diátaxis ↩
A framework for organizing technical documentation into four types: tutorials, how-to guides, reference, and explanation.
LLM ↩
Large language model, a type of AI system trained on large amounts of text to generate and edit language.

Reference links

Diátaxis and related docs frameworks

Alternative documentation models

  • Seven action model
    Alternative framework that organizes docs around user actions like appraise, explore, practice, and troubleshoot.

Examples and prior discussion