Excellent points on documenting the intention and design decisions, not just the "what".
I also use the following metaphor using an airplane:
There are three types of documentation:
1. 800 page manual with page 1 being "Congratulations on purchasing your 747!"
2. 10 page "How to change the oil in the engine"
3. 5 item checklist "How to deal with a fire in the engine"
Too many people think documentation is just one of the above. And if you are a developer, #1 feels overwhelming to write but the SREs may only want #3 (and may even help you write it).
This reminds me of the Diátaxis framework [0], which has a nice visual representation of the different types of documentation.
They have a fourth type they call "Explanation" that's "Here's why we made the flaps behave this way, and how that relates to the theory of aerodynamics"
Agreed.
I remember hearing very good talk from someone working on Django documentations that was very close to what you describe.
Cannot find the reference to the talk, but indeed this is how the documentation is organized:
https://docs.djangoproject.com/en/5.2/#how-the-documentation...
I also use the following metaphor using an airplane:
There are three types of documentation:
1. 800 page manual with page 1 being "Congratulations on purchasing your 747!"
2. 10 page "How to change the oil in the engine"
3. 5 item checklist "How to deal with a fire in the engine"
Too many people think documentation is just one of the above. And if you are a developer, #1 feels overwhelming to write but the SREs may only want #3 (and may even help you write it).