Hi Stephen Thank you for your message. I'll respond just to a few of your comments.
HOW MUCH EFFORT ON DOCS ========================== Myself and you wrote: >> Summary: Discussion of the words 'jargon' and 'chatter'. Recommend >> that we learn better how to find a compromise (strike a balance) >> between precision and simplicity. > I'm not a big fan of asking that everybody put such effort into > documentation for code they're developing. IMHO, where available users > should just buy books by professional writers written to their level, > rather than imposing this burden on the software development project. Sections 6 and 7 (out of 31) in devguide for the Python project are on this. === https://devguide.python.org/docquality/ https://devguide.python.org/documenting/ === This is about 6.5%, of the devguide, by section count. There are at present 108 open documentation issues (out of about 6,000). This is about 2%. I'm proposing for example that we review, and if possible improve, these two sections in the devguide. This review would be evidence based. Not everyone need be involved in this. I suggest that doing this now would, over 3 years, significantly improve our Python documentation. AN EXAMPLE - super() ================== By chance, I wanted today to read about and then use super(). I found === https://docs.python.org/3/library/functions.html#super For practical suggestions on how to design cooperative classes using super(), see guide to using super(). === To my surprise, I found that this links, not to another part of the docs, but to === https://rhettinger.wordpress.com/2011/05/26/super-considered-super/ === This excellent blog post is not, of course, indexed for the docs search. THE GLOSSARY ============= You wrote: > The missed opportunity is that a good glossary will also serve users > who graduate to "informal write-only documentation" including archives > of mailing lists and group chats, and the issue tracker. Five days ago, I raised an issue (one of the 108 open issues), to improve search in the glossary. And thanks to Ammar Askar, there's already a patch and pull request. This delights me. https://bugs.python.org/issue34398 https://github.com/python/cpython/pull/8773 TRANSLATION ============ You wrote: > Serving non-native-speakers is a tough call. On the one hand, they > would be best served by good translations and glossaries of English > jargon in their native language. There's already prior art on this. See: PEP 545 -- Python Documentation Translations https://www.python.org/dev/peps/pep-0545/ One of the alternatives in PEP 545 is === Simplified English It would be possible to introduce a "simplified English" version like wikipedia did, as discussed on python-dev, targeting English learners and children. === I think this would be a good idea, particularly for the tutorial (and other beginner materials, such as the glossary). -- with best regards Jonathan _______________________________________________ Python-ideas mailing list Python-ideas@python.org https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/
