> Number of times reading the documentation saved time and clarified why: never.
OK, so let's use an example... if you need to e.g. make a quick plot with Matplotlib. You just... what? Block off a couple weeks and read the source code start to finish? Or maybe reduce it to just a couple days, if you're trying to locate and understand the code just for the one type of plot you're trying to create? And the several function calls you need to set it up and display it in the end?
Instead of looking at the docs and figuring out how to do it in 5 or 10 min?
Because I am genuinely baffled here.
Literate programming is not about documenting the public API, it's about documenting the implementation details, right? Otherwise no need for a new name, it's just "API documentation".
> if you need to e.g. make a quick plot with Matplotlib. You just... what?
Read the API documentation.
Now if you need to fix a bug in Matplotlib, or contribute a feature to it, then you read the code.