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:

1. Tutorials
2. How To Guides
3. Explanations
4. Reference documentation

They illustrate the idea using the following image:

You'll see that the space of documentation was broken down along 2 axes:

1. Personal State: Understanding or Executing
2. Task state: 
1. For Understanding: Theoretical vs Real-World 
2. 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 problem on the happy path, without error conditions).
• Tutorials & Training
• Hands on guides against a contrived end goal (eg. Deploying Hello World on K8s)
• User Stories / User walkthroughs
• Common cases being run through without any error cases triggering. (eg. Scaling a cluster up and down)
• Doing a Process: (eg. Development, Onboarding, Debugging, Deployment, Monitoring)
• How to documentation: Walkthroughs of Real-World User Journeys
• This is often the most important documentation set and the last to be written.
• This documentation covers the main "User-Facing Processes" that allow a user to derive value from the system. 
• Doing a Task (Micro Action): (eg. Triggering a system, Issuing a command line)
• Man Pages
• Command line reference guides
• API Pages
• These identify the limits of the system, are very low level and show one "how" to force a particular system component to do what you want. 

Most software teams do a great job on the "Understanding a Theoretical Scenario" -- the design docs, the data flow diagrams, the architectural diagrams are usually in place. Most software teams also do a great job on Doing a Task (the micro actions) -- usually the corresponding code or class is documented, there might be some API documentation, some Javadoc and the reference parameters on the API contracts are well specified. Where most teams lose their users is that they don't proceed to the next level of maturity: the Tutorials and the How-Tos. 

This level of maturity can be assessed with the following hierarchical pyramid of documentation:

The main difference between the Tutorials and the How-Tos is that the Tutorials only cover the happy path in a contrived scenario and the How-Tos cover both the Happy Path and all of the ways the happy path can become unhappy in a real-world scenario. The main goal of the How To documentation is to get a user that's out of the happy path back on the happy path and resolve any open issues. As you can see, how-to documentation is much more challenging to write because it is set in a real-world context in the presence of all the real-world error conditions. 

If we were to use the analogy of a compiler, the tutorials show how to compile and run the program, the man pages show how to customize the compile to suit the user and the how-to documentation shows how to recover from error conditions triggered by the program. 

Only mature programs hit the how-to stage of documentation writing. In order to write the how-to documentation, the program must be robust enough to have the ability to handle all the major error conditions (ideally with a really good error message with detailed instructions on how to address the error condition) and these error conditions must be user-errors and not bugs. This takes time. Once the error conditions have been handled in the application, the how to documentation is written based on how the users are encountering these error conditions (and we are certain that they are not bugs), the program is nearly done and dusted.

It is also for this reason that how to documentation is not written for software that is still under active development. Any error conditions encountered by the user are more likely to be bugs rather than user error. Once how-to documentation has been written for a product, you can be reasonably certain that the software has reached a certain level of maturity. It's also a shortcut for identifying good software -- if the howto documentation is detailed and well organized, the software itself is likely to be mature. 

From a career perspective, you can also use how-to documentation to identify if a software team has reached a level of maturity. Joining a team with a mature piece of software allows you to focus on best practices -- it's good for rapidly learning the best way to do things. It also means that most changes are likely to be incremental. Conversely, a team having little to no documentation, with components running undocumented, with no clear usage guides and regular fires is a team where there's a lot of work to be done to build and stabilize the software. The latter teams are good for early career engineers where doing gets you promoted, the former teams are good for late career folks where getting things done quickly and reliably is paramount. It's also why the more gray haired engineers prefer old-school, rock solid, reliable software - it gets things done with a minimum of fuss. Remember - old software is not a dinosaur, it's a shark. 

If you liked this take on software documentation, please take a couple of minutes to write a comment. I would love to know what you took away from this piece.