github and mailing lists (was: Re: The HTML q element can sometimes be useful. Discuss.)

[subject changed]
[sorry this reply is a bit late; most of it was written a few days ago]

On 2016/04/30 17:59, ishida@w3.org wrote:
> On 29/04/2016 23:03, Tex Texin wrote:
>> Also, github doesn’t maintain the threading as email does. In
>> serializing the responses, it isn’t clear (as far as I can tell) which
>> comment a reply refers to.
>>
>> It isn’t clear to me either how much of the original mail I should cut
>> and paste into a reply, and as the formatting is changed, it loses
>> some of the indications of who said what.
>
>
> In github issues the overall threading tends to be maintained better
> than by our email archives,

I'm not sure that's true. Email can show full (i.e. three-structured) 
threading very clearly, based e.g. on the References: header. That only 
breaks down when somebody uses a mail user agent that doesn't use that 
header.

"Theading" on github is simply linear. That's okay for small issues and 
cases when the discussion proceeds linearly, but not for more 
complicated situations.

> but yes you may sometimes need to manually
> copy the bits of the previous message you want to reply to when using
> the github interface.

Yes indeed. The problem is that in github, the thread is just before 
your eyes, and active effort is needed to copy stuff, and so in most 
cases, there's not enough copying, in particular for people who read the 
messages as email.

> On the other hand, this tends to provide a major
> benefit for others in that the writer of the email only repeats stuff
> when needed, reducing clutter and focusing in on the specific idea they
> are replying to.

I fully agree that replying without reducing quoted text is a bad idea 
in most cases. The problem is that when using email, there's usually too 
much context, and when using github, there's usually not enough context. 
The ideal is somewhere in the middle.

> Much of the time, however, if you look at github issue lists you'll see
> that none of the original mail is pasted into the reply, since the stuff
> you are reacting to is close to hand already. This tends to make it
> easier for others to follow the thread later.

If they follow it on github, that is. Not necessarily so in email.

The clearest example is closing a thead. In github, the close is at the 
bottom, with the reason for it just above in most cases. In email, it's 
a virtually useless message, in particular if it's the only message one 
receives after the one that initiated the discussion.

> If you start sending replies via email, please reduce the original text
> as much as possible,

Yes, please. That applies for any kind of email, anyway, but needs 
repeating occasionally.

> and preferably to none at all.

Well, please always consider that some people will receive your comment 
as an email, and in that case, even a tiny bit of context helps a lot.

> Another difference between email and issues is that the latter tend to
> stay more on-topic.  If someone wants to start a subtopic they can raise
> a new issue.  Note, for example, how this subthread about using github
> would is polluting the main thread in the email client, but is not doing
> so for the github issue thread! ;-)
>
> For me, issue-based discussions tend to produce threads that are more
> easily read by others, especially after the discussion has taken place.
>  This shift in perspective is extremely helpful in the longer term, or
> even briefly outside the moment of activity.

This is a valid point. However, there are other systems that are better 
at integrating email and issues/bugs/features. The one I know best is 
redmine. When commenting, you can essentially select "comment" or 
"comment with quoting". And then of course you can tweak by hand. This 
solves github's "manual copy" problem when needed. Also, the original 
proposal is always added at the bottom of each email. This makes emails 
a bit heavier (but bits are cheap these days), but always provides some 
basic context.


> Here are some additional ideas i just found by doing a Google search, by
> Ben Balter*. They seem to reflect what i hear from others:
>
> "The great thing about issues and pull requests, in contrast to say,
> email, is that they can be bifurcated when topics diverge. This keeps
> teams focused on shipping one thing and only one thing at a time.
> Additionally, discrete topics minimize unnecessary noise and optimize
> for fast decision making by ensuring only the most relevant teams are
> involved.

Email threads can be bifurcated, too. It may be a bit less usual, but 
it's not impossible.


> "In practice, that means discussions should have one purpose, defined by
> the title at the top of the page. When a concern not directly related to
> the thread’s purpose arises through the course of the discussion, as
> they often do, open a new issue and encourage participants to continue
> the discussion there, or if you see a teammate hijacking the discussion,
> do the same on their behalf. If the sub-task is a blocker, note it as
> such, and move on."

This is okay for small, clearly identifiable issues, but not for bigger 
stuff. And often choosing the issues in and by itself amounts to making 
decisions.

> ...
>
> "Email is a terrible, terrible collaboration medium, and an even worse
> mechanism for storing organizational knowledge. There’s no opt-in or
> opt-out mechanisms, no ability to link to or cross-reference
> discussions, and conversation history lives in a teammate’s personal
> inbox, so when they leave so too does the issue’s context. Use email
> sparingly, and only when issues or chat, exposed to the company, would
> be inappropriate for the conversation. Put another way, email is for
> sensitive conversations.

That clearly assumes that email is restricted to 1-to-1 communication 
(of course we have mailing lists) and isn't archived except on the 
recipients' computers (of course we have mailing list archives) and 
mails in archives cannot be linked to (of course they can, and the 
Archived-At header used with W3C (and other) mailing lists makes this 
very easy).


> In practice, that means email is typically reserved only for things like
> personnel discussions, one-to-one feedback, and external communication.
> The same goes for other mediums (like phone calls) that don’t
> automatically capture and surface context. If you can have the
> conversation in a better medium, you should."

If email were that bad, I seriously wonder how the IETF and the W3C 
managed to work for the past 20 or so year.


> http://ben.balter.com/2014/11/06/rules-of-communicating-at-github/

Please note that the title of this is "15 rules for communicating at 
GitHub". Of course, GitHub uses GitHub for most of what it does. It's 
like Microsoft using MS Word, or the W3C using Web pages, or so. Eat 
your own dog food.


> * "Named one of the top 25 most influential people in government and
> technology and Fed 50’s Disruptor of the Year, described by the US Chief
> Technology Officer as one of “the baddest of the badass innovators,” and
> winner of the Open Source People’s Choice Award, Ben Balter is a Product
> Manager at GitHub,"

I don't mind big credentials, but I'd prefer stuff being judged based on 
facts (e.g. the existence of mailing lists and archives,...).

Regards,    Martin.

Received on Friday, 6 May 2016 08:54:36 UTC