Diátaxis(diataxis.fr)
385 points by ryanseys 16 hours ago | 48 comments
tl;dr: Diátaxis is a documentation framework that organizes technical writing into four distinct types based on user needs: tutorials, how-to guides, reference, and explanation. It addresses what to write, how to write it, and how to structure it, without imposing heavy implementation constraints. The approach has been adopted by projects at Cloudflare, Gatsby, and others to improve documentation architecture and discoverability.
HN Discussion:
  • Diátaxis is an excellent framework that clarifies documentation writing and voice
  • ~Useful framework but shouldn't be treated as gospel; maintenance and drift remain challenges
  • Skeptical of its value except as a convenient prompt for LLM-generated docs
  • Provides helpful context like translations, etymology, or origins (Divio precursor)
  • Concrete examples (like cooking) make the philosophy resonate beyond software docs