[Python-ideas] Clearer communication
Steven D'Aprano
steve at pearwood.info
Sat Feb 2 07:43:52 EST 2019
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
More information about the Python-ideas
mailing list