Documentation is the most valuable if it captures the design decision and intention at the time of the creation of the software, rather than the functionality of the software itself.
Its pointless to write "This function splits the input data into two equally sized chunks, multiplies each chunk with Y and then adds it together"
It makes more sense to write "The hardware X that this code runs on has a cache size of Y which makes this split necessary for optimal compute throughput".
This provides the next person an understanding of why the code looks as it does, and if it should be changed at this new moment in time, when perhaps new hardware is available.
I have seen so many design decisions being forgotten with time, and despite "documented code", a new engineer comes in and spends weeks trying to solve something that it inherently correct or is there for a good reason.
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...
This is also why you should write your tests before you write the code. Far too many tests just test what the code already does. I don't care what it does, I care what it was supposed to do.
I think of this is answering the questions of what vs why. When what is being done is self-evident, that's readable code. When why it's being done is evident, that's good documentation. And, you need both.
This sort of documentation philosophy is part of US regulatory practices. The history of the enabling legislation is available online for all US regulations, as well as open comments made and agency responses to those comments.
“The most common reason for legislative history research is to determine the legislature's reason for creating or amending the law or the meaning of a term used in the law. This type of research finds the legislative intent.”
"// Divides by 2" is the worst kind of comment and the unfortunate part is that thanks to "AI autocomplete" these will only be merged even more often [raises hand for forgetting to delete this instruction]
Its pointless to write "This function splits the input data into two equally sized chunks, multiplies each chunk with Y and then adds it together"
It makes more sense to write "The hardware X that this code runs on has a cache size of Y which makes this split necessary for optimal compute throughput".
This provides the next person an understanding of why the code looks as it does, and if it should be changed at this new moment in time, when perhaps new hardware is available.
I have seen so many design decisions being forgotten with time, and despite "documented code", a new engineer comes in and spends weeks trying to solve something that it inherently correct or is there for a good reason.