> Source code answers the how and what but it doesn't provide any answer to the most important question of all - why? The vast majority of technical documentat

> Source code answers the how and what but it doesn't provide any answer to the most important question of all - why? The vast majority of technical documentation I read doesn't answer why, either. The closest examples I see these days are tech talks (e.g., videos of Rich Hickey talks) and FAQs (e.g., the Python FAQ has a number of "why" questions). Sometimes also source code comments (e.g., the Swift stdlib actually has fairly informative comments). For some reason, even though there is clearly demand for the why, and programmers are happy to supply it, nobody ever wants to provide it inline, in the documentation proper. It's a rare, rare piece of software that doesn't at some point make me tear my hair out and ask "why?!" upon discovering some behavior which is working exactly as documented.