[SciPy-Dev] establishing a Code of Conduct for SciPy

[Matthew Brett]

On Tue, Oct 3, 2017 at 12:28 AM, Bennet Fauber <bennet at umich.edu> wrote:
> I am more a lurker than a contributor, but I would like to suggest
> caution with respect to item #5 in the proposed CoC.
>
> +5. Be concise. Keep in mind that what you write once will be read by hundreds
> + of persons. Writing a short email means people can understand the
> + conversation as efficiently as possible. Short emails should always strive
> + to be empathetic, welcoming, friendly and patient. When a long explanation
> + is necessary, consider adding a summary.
>
> I suggest that you should stress more that people should strive for
> clarity and completeness, and then say that brief and comprehensive is
> the desired goal.  I think you're leaning on short too hard, and that
> will encourage incomplete more than real concision.
>
> There are my reasons:  1) one person's concise could well be another's
> incomplete.  2) There are many, many terms that have more than one
> use, or that have different meanings in different contexts, or may
> have connotations; sometimes being concise leads to use of seemingly
> unambiguous terms that do turn out to be ambiguous.
>
> For those who would reply that the definition of 'concise' implies
> completeness, as in the definition given:
>
>     giving a lot of information clearly and in a few words; brief but
> comprehensive.
>
> In popular speech, and to those who may have been over-exposed to some
> kinds of management, concise is more likely to be interpreted as
> 'abbreviated', which highlights my second point above.  I myself often
> interpret 'concise' to mean 'short' and often 'abbreviated', because
> that is what I have (alas) become accustomed to in my work
> environment.
>
> Language evolved to have a lot of redundancy built into it for a
> reason.  Stripping it of too much is as bad as including too much.
>
> I hope I was sufficiently concise.  ;-)

I agree with the general idea.  Concise emails can be very
intimidating, as in "it's so obvious you are wrong I can't be bothered
to explain why".  It's can also be an alienating sign, as in "I'm so
senior here that there is no need for me to explain my reasoning".

Maybe a better way to put it, is something like "Try to help your
audience; your email will be read by hundreds of people, and many
people will read only a few lines to decide if they are interested.
Do you best to get to the point as fast as you can, so people can see
what the email will be about.  It is often useful to put a summary of
a few lines at the top and then explain your reasoning in more depth
below, for people who want to learn more."  We could point to a few
good examples.

Cheers,

Matthew