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).
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).