Comment by cxr

> Programmers tend to carry over the structure of the program as the structure for its documentation[…] the right way to structure documentation is according to the concepts and questions that a user will have in mind when reading it.

That's also the right way to structure the program. Deficient compilers and bad advice have done serious damage to source code comprehensibility.