May 10, 2020

Asynchronous communication for open source projects

This is a suggestion for organising asynchronous communication for open source projects.

I first drafted a modified version of this blog post as a contribution to an open source project. The aim of this contribution was to suggest how values of the project: openness, inclusivity, and transparency, translates when it comes to communication amongst present and future contributors and maintainers.

We would like people to feel that they can join the conversation whenever they want and contribute at their own pace. In that aspect, the role of contributors should be to make sure that present and future contributors can do so. Contributors should convey the ethos by keeping the project open, inclusive, transparent. That is by making sure all contributors have access to all communication.

We believe that the time and effort people contribute to an open source project should remain under their control. Contributing to an open source project should not become a burden for a contributor. Contributors should not feel pressured to work; that is coding, reporting bugs, translating, documenting, joining or monitoring conversation or even responding to a message synchronously. Contributors can join at their own will, contribute at their own pace. Contributors are responsible to assess the relevance and the scope of their contributions before opening a pull request. We encourage present and future contributors to inquiry by opening an issue if they have any questions.

A repository is the agora for maintainers, contributors and users. If one feels like they have something to say, a comment, a feedback, an idea, a suggestion, a feature request, a bug report; they should do so in an issue. Issues are the place for those conversations; we believe that it is best to open issue when in doubts, than not to.

Before one opens an issue they should search through open and closed issues to check if:

  • there is an issue that conveys what they have to say; if so they should carry on the conversation in that issue;
  • one or multiple issues that are related to what they have to say, but do not convey the full message, they should open a new issue, and carry on the conversation referencing past related issues;
  • their issue was dealt with in the past and is now closed.

All conversations should be deemed a space on the repository. It is best to open an issue, comment and have a say, rather than not. If an issue is a duplicate, or related to some other conversation, contributors will close it and reference the relevant issue. Do your own research; be considerate of other contributors’ time and attention.

Opening an issue to start a conversation can seem daunting. It should not be. It is expected that contributors write so others can join the conversation. All conversations should take place on the repository for the sake of openness, inclusivity, and transparency.

The repository as an asynchronous communication platform:

  • allows for the pace of a conversation to be adequate so all contributors have a chance to join;
  • allows necessary time for contributors to think and reflect before starting, or joining a conversation;
  • allows contributors with different schedules, obligations, or in different time zones, enough time to join a conversation;
  • allows contributors to join any conversations about the development of the product;
  • allows contributors to create thoughtful conversations that can be seamlessly transferred to a Wiki, a Help page, or Documentation;
  • allows contributors to find their way throughout past conversations since conversations are structured and organised by subjects;
  • prevents collaboration overload (that is for contributors to spend less time organising” and more time contributing to documentation, code, translations, design, bug reporting, etc);
  • allows for necessary time and space to produce higher quality conversations.

As the founder of Doist puts it, asynchronous communication is when you send a message without expecting an immediate response”.

I would also add that asynchronous communication tools tend to organise conversations by subjects (e.g. “Fix update button”) rather than topics (e.g. “#bugs.”) With asynchronous tools such as a repository’s issue system or a forum, conversations are organised by subject. Conversations organised by subjects are separated from one another; once they are terminated they can be closed, and archived, and don’t clutter the issue/forum board where all active conversations live. With synchronous tools such as Slack, conversation are organised by topic. Conversations all live on the timeline of a same topic and can’t be closed or archived. In asynchronous tools tags are a substitute for synchronous tools’s topics.

Contributors might find it easier to navigate conversations by subjects and tags, rather than topics and conversational timelines.

Conversations outside a project’s repository — if a contributor decide to contact a contributor outside of the project’s repository, they should be considerate:

  • contributors have different schedules, obligations, and live in various time zones;
  • conversations taking place outside the project’s repository arbitrary seclude other contributors;
  • conversations taking place outside the project’s repository might be concurrent and risk conflicting at some point.

Sometimes synchronous, or instant message (IM), communication can help. E.g. when working in pairs, code reviews, mentoring, dealing with emergency, etc. If one happens to do so they should make necessary effort to document the off repo” conversation in an issue. That said:

Synchronous communication should be the exception, not the rule.”– Amir Salihefendic, founder and CEO of Doist

Other read on asynchronous communication:
  • How to foster an asynchronous communication culture (coming soon — sign up for the newsletter or follow RSS feed to be notified).

open source how-to slow web well-being

No affiliates, No Google Analytics, No Facebook Pixel. © 2016-2021 Romain Aubert. Content is licensed under a CC BY-NC-SA 4.0. About this site.