Showing posts from 2023

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 . 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 solve a p

The day I met Whit Diffie (of the Diffie-Hellman crypto fame)

It was either December 11th or December 18th. It was a neighborhood party at Didi's place. Honored to meet a Turing Award winner. I was too tongue tied to say anything beyond platitudes though. Tons of respect for what he's achieved.