I would consider conciseness and accuracy most important. Using jargon but linking to accurate explanations would, in my not exactly humble opinion, be the best way to go about it.

...

Summary: I look at the phrase 'strike a balance' in different languages,

It is interesting that you picked up on "strike a balance" which has been a standard English phrase for a very long time rather than the much more resent, (and itself a form of jargon), "dumbing down".

The other point is that the use of Jargon is often as a form of shorthand so as to avoid excessive verbosity, (or long windedness).

We are (maybe) mingling two issues here -- there is an important distinction between idiomatic expressions ("striking a balance", "dumbing down") and technical terms (jargon). If you want to make it easier for non-native english speakers to understand -- minimal use of idiomatic expressions is a good idea. They really don't serve much real purpose, other than making the prose more colorful and friendly (to those that understand it). Sometimes a bit of brevity is gained, but not much. Technical jargon, on the other hand, can be very helpful for precision and compactness. (side note -- are all domain-specific technical term "jargon"? I tend to see "jargon" as having a negative connotation -- specifically that it isn't required for technical specificity. That is, "jargon" is language that is unnecessarily domain specific) I think it's pretty important to use the common domain specific terms in introductory texts -- how else will folks learn them? So I make a distinction between *using* a technical term, and *introducing* a technical term. In fact, in my PR on Jonathan's doc on None, I deliberately introduced the term "Singleton" -- not because it was necessary to understand the idea at hand, but because people are likely to encounter the term elsewhere. -CHB -- Christopher Barker, Ph.D. Oceanographer Emergency Response Division NOAA/NOS/OR&R (206) 526-6959 voice 7600 Sand Point Way NE (206) 526-6329 fax Seattle, WA 98115 (206) 526-6317 main reception Chris.Barker@noaa.gov

On 8/20/2018 5:13 PM, Barry Scott wrote:

...

On 20 Aug 2018, at 17:07, Chris Barker via Python-ideas mailto:python-ideas@python.org> wrote:

> Summary: I look at the phrase 'strike a balance' in different languages,

It is interesting that you picked up on "strike a balance" which has been a standard English phrase for a very long time rather than the much more resent, (and itself a form of jargon), "dumbing down".

The other point is that the use of Jargon is often as a form of shorthand so as to avoid excessive verbosity, (or long windedness).

We are (maybe) mingling two issues here --  there is an important distinction between idiomatic expressions ("striking a balance", "dumbing down") and technical terms (jargon).

If you want to make it easier for non-native english speakers to understand -- minimal use of idiomatic expressions is a good idea. They really don't serve much real purpose, other than making the prose more colorful and friendly (to those that understand it). Sometimes a bit of brevity is gained, but not much.

The technical writing course I went on as an engineer years ago recommenced "Controlled English" in documentation. Its good for none english speakers and the lack of colloquial expression means English speaks are not miss lead.

As you say this is nothing to do with jargon.

...

Technical jargon, on the other hand, can be very helpful for precision and compactness.

It also means you will understand other people doing the same activity. Be they musicians or programmers.

...

(side note -- are all domain-specific technical term "jargon"? I tend to see "jargon" as having a negative connotation -- specifically that it isn't required for technical specificity. That is, "jargon" is language that is unnecessarily domain specific)

I found this definition:

"J/argon/. A special language belonging exclusively to a group, often a profession. Engineers, lawyers, doctors, tax analysts, and the like all use /jargon/ to exchange complex information efficiently. /Jargon/ is often unintelligible to those outside the group that uses it."

To me, 'jargon' refers more to in-group replacements for common words (slang) than to technical terms. 'Hack the bug' for 'Fix the program error' is an example of the former. 'Use a coroutine' uses a technical term that needs several sentences and some preliminary knowledge about functions to explain. In any case, docs should avoid slangy jargon and explain technical terms.

Not all group members remember to avoid jargon > when talking to people outside the group. If you are on the outside looking in at the people that will not explain in plain english you could well consider jargon as a bad thing.

...

I think it's pretty important to use the common domain specific terms in introductory texts -- how else will folks learn them? So I make a distinction between *using* a technical term, and *introducing* a technical term.

Yes.

-- Terry Jan Reedy

Nick Loadholtes wrote (elsewhere, quoted in this thread - by me).

Make your docs work as hard as your code does. Clear examples will make your code stand out in a good way.

With a bit more searching I found: <quote> https://www.reddit.com/r/Python/comments/70myto/whats_new_in_python_37_pytho... I'll disagree. Nothing is better than Mathworks documentation. I like documentation by example. Python gives you the dry, technically correct verbiage behind how something works. Matlab says: "Here, copy paste this and it'll work". To the point that the workspace is designed to automatically strip >>> from any copy and pasted commands. Even with most Python examples you can't just copy and paste a chunk of an example from the web or documentation because you need to clean off >>> first. </quote> It did me good, to read the resulting discussion on reddit. -- Jonathan

Hi Steve You wrote:

I would just like to point out that the ipython %paste magic very handily strips leading >, ... & + characters from the pasted block, (there is also some clever dedenting done).

[useful example, snipped]

Which is ideal. I personally find that many beginners get on a lot better in the iPython console than in the python one.

Thank you very much for this. I didn't know about this solution to the problem. Docs search for ipython brings up <quote> https://docs.python.org/3/tutorial/interactive.html One alternative enhanced interactive interpreter that has been around for quite some time is IPython, which features tab completion, object exploration and advanced history management. It can also be thoroughly customized and embedded into other applications. Another similar enhanced interactive environment is bpython. </quote> I've now played a little with (both look nice):

https://www.bpython-interpreter.org https://repl.it/repls/LightcoralMoralDistributedcomputing

Perhaps beginners would benefit from something better than the default, but simpler than ipython. But I don't have any experience to support this view. There's related prior art in the well-regarded https://codewith.mu/en/about. (Steve, I'd welcome your comments on this.) So thank you for bringing iPython's nifty %paste trick to my (and the thread's) attention. -- Jonathan

Chris Angelico wrote

Where in the linked-to What's New page is there an example of that? There are several code blocks that ARE copy/pasteable, even into the vanilla interpreter.

Good question. The reddit user wrote. <quote> https://www.reddit.com/r/Python/comments/70myto/whats_new_in_python_37_pytho... Take this example for re.sub. [https://docs.python.org/3/library/re.html#re.sub] Trying that out requires 3 separate copy and pastes just to do one example. Or you have to put it in an intermediate file, clean it up then paste it in. The examples are also grouped by sub function not by what they do. </quote> I think the problem is the user didn't see the [>>>] toggle at the top right of the code block. I know I didn't just now, when I tried it just now. It was only the strength of your assertion, Chris, that made me go back and try again. <quote> https://docs.python.org/3/tutorial/introduction.html In the following examples, input and output are distinguished by the presence or absence of prompts (>>> and …): to repeat the example, you must type everything after the prompt, when the prompt appears; lines that do not begin with a prompt are output from the interpreter. Note that a secondary prompt on a line by itself in an example means you must type a blank line; this is used to end a multi-line command. </quote> No mention here, or elsewhere on the page, that [>>>] at the top right of a code example toggles the presence or absence of prompts. -- Jonathan

Jonathan Fine wrote:

Matlab says: "Here, copy paste this and it'll work".

To the point that the workspace is designed to automatically strip >>> from any copy and pasted commands.

Maybe this is something Python's REPL should do? -- Greg

On Tue, Aug 21, 2018 at 3:07 PM, Jonathan Fine wrote:

...

Maybe this is something Python's REPL should do?

Good idea.

I can't find (with very little effort) any documentation of this, but I have a vague recollection that the core devs want to keep the built-in REPL really simple -- more advanced features are for third party packages like iPython. I tend to agree -- while something like this: "making the built-in repl more friendly t copy-and-paste from examples" seems like a no brainer, the fact is that there are a LOT of features that would make it easier for newbies, and in the end, you'd end up with something like iPython. Honestly, Python does "suffer" a bit when in competition with commercial products, in that it is a language (and an implementation of that language), not an entire programming environment. So to use it, you need to figure out which Editor or IDE you want to use, what debugger, etc..... And the REPL, while being pretty key to interactive data analysis, is not a key feature of programming languages in general, even interpreted ones. So the solution is: use a third party solution for a complete environment suitable for your needs. For instance, for people doing data analysis, I recommend Anaconda -- then you get iPython and JUpyter (and Spyder) out of the box -- and away we go. maybe it's worth a note t pyton-dev to confirm my vague impression (or some more thorough googling for previous discussions) -- but I wouldn't put much effort into ideas for the REPL without confirming that the core dev are open to the concept. -CHB -- Christopher Barker, Ph.D. Oceanographer Emergency Response Division NOAA/NOS/OR&R (206) 526-6959 voice 7600 Sand Point Way NE (206) 526-6329 fax Seattle, WA 98115 (206) 526-6317 main reception Chris.Barker@noaa.gov

%edit -p

Bring up an editor and execute the resulting code.

-p: this will call the editor with the same data as the previous time it was used, regardless of how long ago (in your current session) it was.

https://ipython.readthedocs.io/en/stable/interactive/magics.html#magic-edit Something like this that calls $EDITOR with a temp file would be useful in the Python REPL as well. On Wednesday, August 22, 2018, Antoine Pitrou wrote:

...

On Tue, Aug 21, 2018 at 3:07 PM, Jonathan Fine wrote:

...

...

Maybe this is something Python's REPL should do?

Good idea.

I can't find (with very little effort) any documentation of this, but I have a vague recollection that the core devs want to keep the built-in REPL really simple -- more advanced features are for third party packages like iPython.

I tend to agree -- while something like this: "making the built-in repl more friendly t copy-and-paste from examples" seems like a no brainer,

On Wed, 22 Aug 2018 09:38:57 -0700 Chris Barker via Python-ideas wrote: the

...

fact is that there are a LOT of features that would make it easier for newbies, and in the end, you'd end up with something like iPython.

Honestly, Python does "suffer" a bit when in competition with commercial products, in that it is a language (and an implementation of that language), not an entire programming environment. So to use it, you need to figure out which Editor or IDE you want to use, what debugger, etc.....

And the REPL, while being pretty key to interactive data analysis, is not a key feature of programming languages in general, even interpreted ones.

So the solution is: use a third party solution for a complete environment suitable for your needs. For instance, for people doing data analysis, I recommend Anaconda -- then you get iPython and JUpyter (and Spyder) out of the box -- and away we go.

maybe it's worth a note t pyton-dev to confirm my vague impression (or some more thorough googling for previous discussions) -- but I wouldn't put much effort into ideas for the REPL without confirming that the core dev are open to the concept.

To me it sounds fine to improve the REPL. Especially, being able to paste examples without effort was a sore point for me until I finally switched to IPython. How much complexity and development work that would entail I don't know, though :-)

Regards

Antoine.

_______________________________________________ Python-ideas mailing list Python-ideas@python.org https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/

On Wed, Aug 22, 2018 at 06:01:05PM -0400, Wes Turner wrote:

%edit -p

...

Bring up an editor and execute the resulting code.

https://code.activestate.com/recipes/578926-call-out-to-an-external-editor/ -- Steve

On Wed, Aug 22, 2018 at 7:47 PM Mike Miller wrote:

...

...

On Tue, Aug 21, 2018 at 3:07 PM, Jonathan Fine wrote:

...

...

Maybe this is something Python's REPL should do? iPython brings in a lot of functionality, perhaps too much. Would prefer something more focused like bpython or ptpython.

Happily, you know where to get IPython, and BPython, and PTPython. Different users have different desires for an enhanced REPL, and different good, free software, projects exist. I would tend to oppose most of these "fixes" to the basic Python REPL as "feature creep." Full featured interactive shells are great. I use IPython and Jupyter dozens of times every day myself. I love those. But they make specific decisions on what and how to enhance things, and have a huge range of configuration options. The `python` REPL should really be just good enough to use, and allow other projects to provide the richer experience (and to maintain all the code associated with making them powerful and flexible). Obviously, that's not saying categorically that "nothing can ever change" in the Python REPL. But most things I would lean against adding. It does basically as much as it should, with no more code than is necessary to do that. -- Keeping medicines from the bloodstreams of the sick; food from the bellies of the hungry; books from the hands of the uneducated; technology from the underdeveloped; and putting advocates of freedom in prisons. Intellectual property is to the 21st century what the slave trade was to the 16th.