> Instead, I recommend starting by documenting the key behaviour of the program, describing its model of the world and defining terminology, and only then trying to document each function in terms of that model and terminology.
Can you explain in more detail how that's different from the approach described in "What nobody tells you about documentation"? [0] At first blush, your recommendation sounds pretty similar to what is suggested in that post.
Is this a critique of the guideline to "Give reference documentation the same structure as the codebase" that was in [0], or is it more like you think the importance of the "Explanation" section is underrated?
(This is coming purely from the perspective of somebody who is trying to write better documentation. I'm not trying to defend any particular stance, just interested in your opinion.)