[Python-ideas] Clearer communication

[Steven D'Aprano]

On Fri, Feb 01, 2019 at 11:40:37AM -0500, James Lu wrote:

> So I want an open discussion on: How can we communicate clearer?

Remember the Curse of Knowledge: just because you know something, don't 
imagine that all your readers know it too.

https://en.wikipedia.org/wiki/Curse_of_knowledge

https://www.psychologicalscience.org/observer/the-curse-of-knowledge-pinker-describes-a-key-cause-of-bad-writing

https://sites.williams.edu/nk2/files/2011/08/Curse_of_Knowledge.pdf

Try putting yourself in the reader's position. Will they understand what 
you are talking about? Re-read (and edit) your email for clarity before 
you hit send.

Read your own email when it arrives in your inbox. If there are any 
major mistakes or confusing bits, reply to the list and clarify. With 
luck, maybe people will read your clarification before they respond.

Try not to make rapid-fire knee-jerk responses to other people. (I know 
that's one bit of advice I personally find hard to follow.)

Try to write clear and precise language.

https://www.butte.edu/departments/cas/tipsheets/style_purpose_strategy/writing_clearly.html

But note that *clear* and *precise* are often opposed to each other. The 
page above gives an example:

    The biota exhibited a one hundred percent mortality response.

    All the fish died.

but the two sentences don't mean the same thing. (In the first, 
*everything* died; in the second, only the fish died.)

Jargon is a double-edged sword for this reason: not everyone will know 
what the jargon means, but for those that do, jargon terms are both 
concise and precise in ways that plain English terms usually are not. As 
programmers, we use a lot of jargon, but remember than not everyone has 
the same background. My obvious technical term may be your obfuscatory 
gibberish.

If you expect that a jargon term will be unfamiliar, either explain what 
you mean, or give a link to a site that explains it. If you're not sure 
whether a jargon term will be unfamiliar to others, remember the Curse 
of Knowledge: it probably will be.

Remember that *most ideas are bad* -- that is equally true here as on 
Wikipedia:

https://en.wikipedia.org/wiki/Wikipedia:Most_ideas_are_bad

Be critical about your own ideas before you post. Try to anticipate 
objections. Either you will decide the objections are right, or you may 
be able to pre-empt them.

Have a bit of humility: just because others disagree with you, doesn't 
mean that they haven't understood you. Perhaps they have understood your 
idea and its consequences better than you have yourself.

It is *really hard* to read criticism of your ideas, but necessary. If 
the criticism was valid, then either your idea needs to fixed to avoid 
the problems given, or it needs to be abandoned as unfixable.

Remember too that sometimes there is no right or wrong answer, just a 
matter of taste, or of value judgements. This especially applies when 
there are trade-offs involved. As a language, Python makes many 
trade-offs (as do all other languages). Some ideas are not bad in and of 
themselves, but they go against those trade-offs and consequently 
aren't a good fit for Python.

On the flip side, sometimes we're too quick to reject ideas because 
they've never been done before. For some definition of "never". (Usually 
"never that I know of, not that I've looked too closely, or at all".) In 
my experience, Python programmers tend to be very conservative, perhaps 
more so than in other communities. Like cats, we often dislike things 
merely because they are new and different.

Consequently sometimes its just a matter of patience and timing. Python 
as a language rarely is a trend-setter. Let other languages take the 
risks, we'll steal the ideas that work and leave those that don't.

This conservativeness is only getting worse, as more of the core devs 
decide that we ought to slow the pace of change down even more, perhaps 
even halt it completely. I don't know what can be done about that.

(Biologists have a word for complex systems which are stable: "dead".)



-- 
Steven