Beginner's Guide to Communication in FOSS
Tags: writing, beginners, opensource
Published: 2020-10-17 23:49:41

Free and Open Source software is maintained by people working remotely from around the world. Hence, effective communication is important for any project to function smoothly. Especially, *asynchronous-written* communication.

I started contributing to FOSS over a year ago. Communication was one of the first things I had to learn. I'm still working on it, but I think I've come a long way. Here are some key points I've picked up.

Before we get to the details, I want to preface this post by saying that asking questions and sharing your thoughts is more important than following any guidelines. You can improve your communication as you go, but never hesitate to speak up because you think it's not "well-phrased". People are nice. People will correct you if you make mistakes. So, the first step is to get involved in the discussion, you can then focus on improving. :)

## Platform matters

There are various "spaces" where people talk — mailing lists, discussion forums, private chat, issue trackers, etc. Each space has it's own guidelines. It's useful to know these while posting messages.

**Mailing lists** - Formal, email-like wording is generally preferred. You can start with a greeting and end with salutation+signature. You are expected to add a relevant subject line. Some people prefer to have a word wrap, it improves readability.

**Discussion forum** - Generally, there is no need for a formal greeting, salutation and signature. It is more informal than an email. Discussion forums typically include IRC, Discourse, Discord, Slack, Zulip, Gitter, Hangouts, and Telegram. Make sure that you understand a little about the platform and the primary reason why the organization uses it. For example, at Bokeh, Slack is used for development discussions and Discourse for community support. Also, note that some platforms like IRC have additional steps like registering your nickname.

**Private message** - You can generally be as informal as in a discussion forum. There are no strict guidelines here, just be nice.

## Mind your language

- **Always, always, always use inclusive language**. I wrote more about this in a [previous post](https://pavithraes.me/posts/plain-english/#inclusive-language-and-biases).
- **Assume positive intent** - Most people are nice and want the best for the project. Sometimes, their words may come across as rude or hurtful. Start with a foundation of positive intent: no-one wants to hurt you. This will allow you to not take criticism personally, and avoid any unnecessary arguments. That said, some behaviour is unacceptable. If any comments violate the project's CoC, please take necessary action.
- **Read the room** - Try to be mindful of the emotions in the room. I'm writing this in 2020 when the world is having a rough year. Having compassion in your words and checking up on people are small acts of kindness that can go a long way.
- **Be open to suggestions** - Everyone has some value to add to the discussion. Be mindful about giving people a chance to express their thoughts and try to understand their point of view.

## Asking questions effectively

- **Research and be specific** -  Take a few minutes to Google your question and go through the project documentation before asking questions. Most of the time, you will find the answer without needing to ask someone. If you can't find the answer after say 10-20 mins of searching yourself, go ahead and post the question. Make sure to mention where you searched and what you found. Sometimes, things get buried in the documentation. Asking questions can surface them and the documentation can be improved.
- **Include all relevant information** - If you are facing a software issue, include relevant information like your operating system, environment, software version, browser info, etc. This helps the developers diagnose the issue accurately, and saves everyone some time.
- **Be bold** - No question is a dumb question. Really!

> For example, instead of "How do I get started with...", try:
>
> "I'm going through the getting started documentation and I'm **stuck at this step**. Here is my **system information** and a **reproducible example**. I've also included a **screenshot** of the issue at the end."

## Please be patient

FOSS contributors and maintainers are volunteers. After posting a question, be patient for folks to answer. It might take them upto 2-3 days to get back to you. If there is a holiday in their country or if it's a weekend, it might take even longer. If you don't get a reply after ~3 working days, you can follow up politely.

## Accent is a speed breaker

This is a fairly recent realization. I have some trouble interacting with people who have a different English accent than me. To be clear, I don't have any trouble in understanding a different English accent, or in speaking English. I just feel like my brain needs to do an extra step of processing and converting before I respond. If you speak more than one language, it's like the bump in the road when you're comprehending in one language and responding in another. (Not exactly, but kind of.)

If this is something you face, it might be a good idea to communicate this openly beforehand.

## Resources

- [How to Win Friends and Influence People](https://en.wikipedia.org/wiki/How_to_Win_Friends_and_Influence_People), a book by Dale Carnegie
- [Summer training - Communication](https://summertraining.readthedocs.io/en/latest/communication.html#)
- [The Secret to Business Writing: Crash Course Business - Soft Skills](https://youtu.be/8E-oqahDnb8)