Sep 7, 2014

Open source email and mailing list etiquette

Over the past few days, I have had quite a few people asking me how to get started contributing to an open source community. To get you going, this blog post takes a look at the email etiquette that you have to follow while communicating with an open source/ FOSS community.


Before you type your email


1. Before you shoot off a mail, use Google or your favorite search engine to thoroughly search for the topic. You may feel the question at hand is unique to you, but the chances are someone else too would have faced this problem in the past, and most likely have had a solution. Save everyone time. Fun activity: Use google to learn how to google!

2. Before you start typing out the mail, learn how to ask the questions the right way. "How do I do that?" you may ask! Worry not, help is at hand.  How To Ask Questions The Smart Way is an excellent resource. Read that article a couple of times. It is a great resource which applies not only to FOSS, but to any aspect in your life.

3. Read the FAQ/beginner guide/developer guide/ getting started tutorial etc. for the community you wish to be a part of. Every community has certain set of guidelines they want to be followed. There usually is a section covering mailing list guidelines for that community. Though the general expected etiquette is almost same everywhere, there is still room for differences between organizations. So read it. It never hurts.

4. Search the mailing list archives of the community. Similar to point 1, there is a great chance of finding a solution over there.

Posting style


If you followed the above steps and still have not found an answer to your
question, you could mail the community via its mailing list asking for help.
The rest of this post covers how to email and reply to email.

1. Do not top post!

This is probably the most important rule. Let us look at what is posting style and why posting style is important - post in the wrong style and get called out by the veterans, not a great experience!

When somebody sends you an email, there are three different styles in which
you could reply.

For example, assume you have sent me the following email.

   From: Me
   To: Saimadhav Heblikar
   Subject: What do you think of qwerty?

   Dear Saimadhav,

   I am interested in doing Foo for Bar.
   But before that, is xyz better than abc?
   .
   .
   .
   So what do you think of X?
   .
   .
   .
   Let me know your overall opinion

   Regards
   Me

I will describe the 3 different posting style below:

   a) Top posting:

       From: Saimadhav Heblikar
       To: Me
       
       Hi,

       Good to know you are interested in doing Foo.
       Xyz is definitely better than abc
       .
       .
       .
       Not a huge fan of X.
       .
       .
       My overall opinion is that i am very enthusiastic.

       Regards
       Saimadhav Heblikar

       > From: Me
       > To: Saimadhav Heblikar
       > Subject: What do you think of qwerty?
       >
       > Dear Saimadhav,
       >
       > I am interested in doing Foo for Bar.
       > But before that, is xyz better than abc?
       > .
       > .
       > .
       > So what do you think of X?
       > .
       > .
       > .
       > Let me know your overall opinion
       >     
       > Regards
       > Me

In top posting style, my reply is above your
initial message. It is very obvious why this style of
replying to emails is not favoured - the answer appears before the question.
The problem is magnified in a long email thread, where there are tens of
replies(and mostly by different people). A nightmare
for anyone interested in reading your replies.
Avoid this style, not just while communicating in a open source community
but in any email conversation.
      

   b) Bottom posting:

       > From: Me
       > To: Saimadhav Heblikar
       > Subject: What do you think of qwerty?
       >       
       > I am interested in doing Foo for Bar.
       > Let me know your overall opinion
       >

       From: Saimadhav Heblikar
       To: Me
       
       Hi,

       Good to know you are interested in doing Foo.
       Xyz is definitely better than abc
       .
       .
       .
       Not a huge fan of X.
       .
       .
       My overall opinion is that i am very enthusiastic.

       Regards
       Saimadhav Heblikar

This style solves the problem of top-posting of the answer appearing before
the question. This is one of the recommended style of replying to emails.
Observe that, I have snipped some your email, by trimming it down.
It is done to avoid repetition and also save some precious bytes.
It may seem like a small amount to you, but remember that most mailing lists have tens of thousands of subscribers - every reply you make is sent to tens of thousands of people - the bytes quickly add up. (Another reason why you should be careful before hitting “Send”.)

   c) Interleaved style:

       From: Saimadhav Heblikar
       To: Me

       >
       > From: Me
       > To: Saimadhav Heblikar
       >
       > I am interested in doing Foo for Bar.
       >
       Good to know you are interested in doing Foo.

       >
       > But before that, is xyz better than abc?
       >
       Xyz is definitely better than abc
       

       Regards
       Saimadhav Heblikar

In this style, context is easy to recognize, for the sender,
receiver and any interested third party. I can also reply to only those
parts which I want to, thereby saving everyone time and space.

While top-posting is big NO-NO, you may follow either bottom posting or
interleaved style. I would recommend that you try to read up on the best
practices of the community before you reply.
If no such resource exist, I recommend that you use bottom posting after trimming the contents, if you reply covers everything the sender asked for.
If you only want to answer certain parts, use interleaved style.

Guidelines for replying


1. Have patience!

Understand that most hackers on open source community do what they do for the passion. They too have a real life, a real job, real hobbies.
They are not doing what they are to help you at your call. Do not send reminder emails. Do not feel that you are entitled to be helped.    

2. Never email someone directly or in private

Just because you managed to obtain someone's email ID does NOT mean you
can email them. You are violating their privacy by doing so. If you have
a question, email the mailing list - for two reasons.
1. You will not intrude on someones privacy.
2. You have a better chance of getting help.

3. No attachments please!

If you find the need to send code files, text files, or any other logs more than few lines long,
do not send them in as attachments. The reason it is frowned upon is:
The mail along with the attachment will be forwarded to thousands of subscribers. It will generate a lot unwanted traffic on the mail server. It will also fill up inboxes of the subscribers.
Remember, not everyone is necessarily interested in the topic you want to discuss.
A solution would be to host your file on a 3rd party server(like gist.github.com) and then link to it in your email.

4. No spamming, trolling, chain emails, personal stories.

Be courteous always. Never email anything which you would not say to that
person directly in real life. Also, we are not really interested in your
story.

Avoid "+1", "me too", "same here" type of posts. This is not your Facebook
or Whatsapp conversation group. This is a serious discussion mailing list forum. Reply only if you have something meaningful to contribute
However, if you are facing the SAME problem, you can help by giving
more information about the problem - how to reproduce it, what are your
system configuration etc.

5. Stay on-topic

It is easy to go off on a tangent during a conversation. Avoid it all costs.
It is misleading to any person in the future who will face a similar problem.

6. Changing the subject of conversation

In some cases, if you have something interesting to say about a related topic, but not exactly the topic at hand, feel free to start a new email thread by editing the subject as follows.

For example, if you want to change the topic of conversation in a discussion called
"reference leaks in v2.0", you may want to do something like:
"How to catch reference leaks(was: reference leaks in v2.0)"

7. However, if you want to go off-topic...

Under some extraordinary circumstances, if you want to post something offtopic, you should prefix the subject with OT(offtopic), like
OT: Is there water on mars?

8. Do not cross-post

Cross-posting is sending the same email to many different mailing list.
You may feel that it gets your problem across to different people.
But in reality, there is great chance that the same set of people are subscribed to most of these list. They will get your email multiple times.
It is very off putting and reduces your chances of getting help.

9. Do not "tyep liek dis & dat"


Poor typing like above and/or bad punctuation will ward off any potential contributor from helping you. It also reflects poorly on you.

Concluding...

If you have read this far, good on you! This post by no means is exhaustive and is only meant to give you an idea on what's expected from you. Search the internet and your community for more such guidelines.

No comments:

Post a Comment