[Python-ideas] Using an appropriate tone in emails (was: Adding a thin wrapper class around the functions in stdlib.heapq)

[Nick Coghlan]

On 28 November 2017 at 13:22, bunslow <bunslow at gmail.com> wrote:
> My first submission to this list was predicated on what I'd read in PEPs --
> and many of those, since they recommend major-enough changes to require a
> PEP, have sections (often lengthy) dedicated to "what's wrong with the
> status quo". My attempt to imitate that obviously crossed some boundaries in
> retrospect, and of course now that it's brought up here I see that spinning
> it as "what can be done to make it better" is psychologically much more
> effective than "why the current way sucks" (because semantically these are
> either approximately or exactly the same). But that's where it came from, at
> least with some of my earlier threads, and I suspect the author of the topic
> message of the OP will have a similar sentiment.

Yeah, by the time someone reaches the point of writing a PEP, there's
usually some level of existing awareness along the lines of "The
status quo might not be OK any more, so let's explicitly document the
risks and benefits associated with a possible change".

That means part of the role of the PEP is to summarise the relevant
problems with the status quo, such that future readers can understand
why any change is being proposed at all.

In cases where the proposed change is relatively simple at a technical
level, like PEP 479 (converting an unhandled StopIteration to
RuntimeError), PEP 538 (coercing the C locale to a UTF-8 based
locale),  or PEP 565 (tweaking the way we handle DeprecationWarning),
the motivation & rationale may end up being the majority of the PEP,
since the actual change to be made is relatively minor, but the
potential consequences aren't necessarily obvious.

By contrast, python-ideas threads usually start at a point earlier in
the decision making process: asking ourselves the question "Is the
status quo still OK?". In most cases the answer is "Yeah, it's still
fine", but we keep asking, because sometimes the answer is "Actually,
we could probably improve it by doing...".

The easiest trap to fall into on that front is to think to ourselves
"The status quo doesn't solve my problems, therefore it doesn't solve
anyone's problems", which usually isn't a productive mindset.

A more productive framing is typically "The problems that the status
quo solves are not the problems that I currently have".

It may seem like a small change, but in the second version, we're thinking:

- the status quo solves problems for someone, just not for me
- whatever I propose should try to avoid making the status quo worse
at what it already does
- I need to explain the problem I have, not just the potential solution I see

and that ends up coming through in the way we write.

I'll also note that nobody expects perfection on this front - most of
us are thoroughly familiar with the lure of "But someone is *wrong* on
the internet" [1], and we know that sometimes it's too late by the
time we finally think "Oh, I really should have toned that down a bit
before hitting Send...". We just strive to ensure our typical approach
is to be respectful of each other, and of past contributors.

Cheers,
Nick.

[1] https://xkcd.com/386/

P.S. For a longer version of the "What problem does it solve?"
question in relation to the respective APIs of the requests and urllib
modules, folks may be interested in
https://www.curiousefficiency.org/posts/2016/08/what-problem-does-it-solve.html

-- 
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia