[Python-ideas] Does jargon make learning more difficult?

[Jonathan Fine]

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