Quality documentation requires Diátaxis
It was an eye opening day for me when I first learnt that there's a theory around how documentation should be organized. That grand unified theory of documentation is called Diátaxis . https://diataxis.fr Diátaxis states that documentation belongs in one of 4 quadrants: Tutorials How To Guides Explanations Reference documentation They illustrate the idea using the following image: You'll see that the space of documentation was broken down along 2 axes: Personal State: Understanding or Executing Task state: For Understanding: Theoretical vs Real-World For Executing in the Real World: Processes (User Flows) vs Tasks (micro actions) The 2x2 breaks down as follows: Understanding a Theoretical Scenario: (What's my model of the world? How is this system solving it?) Architecture Explanations Architecture Diagrams Data Flow Diagrams Algorithms & Theory Design Docs Problem statement / Problem setting Understanding a Real-World Scenario: (Walk me through how I can so...
