Rob Cliffe via Python-ideas writes:
On 01/08/2019 19:11:18, Guido van Rossum wrote:
Here is someone declaring that the docs are less accessible than the code. I personally am disappointed, given the amount of effort that we put in those docs. But maybe this is true. If we can't get people to peruse the docs, should we bother?
One data point: I constantly use the docs and help(). I regard digging into the code as more effort and a second resort. I'm well aware from personal experience that documenting code can be (much) more effort than writing it, but I hope you continue to "bother".
Another data point: I constantly use the docs and help(). I regard digging into the code as a reward for getting $DAYJOB done, but that rarely happens. Let's keep the docs excellent! Sometimes it even helps me get $DAYJOB done.
More seriously, without the docs, all bugs are merely surface tension. "That's what the code does, so it must be right!" That's a somewhat facetious way of expressing that there needs to be a spec independent of the code to settle the "bug vs. feature" arguments, at least during release beta periods.