> On 1 Aug 2019, at 19:11, Guido van Rossum <gu...@python.org > <mailto:gu...@python.org>> wrote: > > This is an interesting phenomenon. I'm not saying it's good or bad, I'm just > observing it (because it surprised me). 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?
Personally I use the docs first, then the code. I do this because I expect to get from the docs the API I can depend on. If I find something useful from read the code that is not documented, I use a my own risk. I have worked with engineers that would not look at the source code if the docs are insufficient. For a product I worked on at a small company we had the "is it worth having docs? No one reads them right?" discussion. The argument that won the day was that reasonable docs reduces support costs. Tech support can point the user at the docs and move on to the next problem. QA team could say all documented features work at each release. Barry
_______________________________________________ Python-ideas mailing list -- python-ideas@python.org To unsubscribe send an email to python-ideas-le...@python.org https://mail.python.org/mailman3/lists/python-ideas.python.org/ Message archived at https://mail.python.org/archives/list/python-ideas@python.org/message/QLYXIDWIYWLZTFAHWPUCRDWUNELC6YYM/ Code of Conduct: http://python.org/psf/codeofconduct/
