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

Thanks for this Martin. I didn't agree with many of Richard's comments but didn't see much point in debating.
At the macro level, using github seems to require different etiquette from email and more importantly requires more work if it means going to the website to reply, or if email is supported then to edit the mail to reduced context etc. and hope that the mail gets placed in the conversations in the right place amongst other simultaneous comments.

That seems like a lot of extra work to solve the problem of people not responding to one of the two lists, compared to reminding people they should respond to both lists.
I also think, if we have a list for discussion, then it is perhaps inappropriate to fork off to github. I have tools and archives for my list mails and the switch disrupts that. 

But I don’t think these lists want a debate on this subject. If others are ok with using Github, we should leave it alone. 
tex

-----Original Message-----
From: Martin J. Dürst [mailto:duerst@it.aoyama.ac.jp] 
Sent: Friday, May 06, 2016 1:54 AM
To: ishida@w3.org; Tex Texin; 'W3C Digital Publishing IG'; 'www International'
Subject: 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 09:37:46 UTC