Diátaxis(diataxis.fr)
549 points by ryanseys 45 days ago | 60 comments
tl;dr: Diátaxis is a documentation framework that organizes content 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, and has been adopted by projects like Cloudflare, Gatsby, and Vonage to improve documentation clarity for both readers and contributors.
HN Discussion:
  • Diátaxis worked excellently in practice for structuring complex documentation projects
  • ~Helpful framework but shouldn't be treated as gospel; read thoroughly before applying
  • ~Great conceptual framework but documentation drift remains an unsolved problem
  • ~Useful primarily as a prompt shortcut for LLM-generated documentation
  • Admirable for its lack of surrounding certification/gatekeeping ecosystem