In the first post of this series, we introduced the concepts of communication barriers that may alienate potential community members. What can we all do to guarantee that everyone feels welcome and that the most talented among us will bring their skills to open source projects? In this second installment on communication in open source, we’ll cover tips on how to not only test your own communication score, but how to improve it overall.
Commit to Communication
Applying communication best practices even further into your project can boost its sustainability and reach. Start with a contributor’s guide that documents how your project operates, the code standards and other practical guidelines. Extend those best practices into your commit messages. Something simple such as clear, complete and well-commented commits can make all the difference. When commits lack clear documentation, new users can find it difficult to understand what changed and why. Further, newcomers won’t know what code or proposed change was already rejected, so they may end up spinning their wheels on a contribution that won’t go anywhere. Likewise, if things start to go south in your project, commit messages that simply read “bug fix” or “small change” won’t provide a great resource for pinpointing what exactly went wrong. It’s like walking into the middle of a complex conversation – you can’t tell what’s going on.
On the contrary, adopting open source communication best practices can help enhance your project’s reach and encourage others to participate. For example, creating good good-first issues makes your project more approachable to newcomers and even people with experience who might just want a better sense of what you are doing. Furthermore, you can increase the chances that they will stay on as contributors, helping you grow your community in a more organic and sustainable way. By establishing a foundation of clear communication from the get-go, others will feel comfortable jumping in on the conversation around your project.
Clear Communication: A Welcome Mat for New Contributors
As a new open source collaborator, the process of contributing to open source can be intimidating, so clear communication up front can help contributors ease into the process.
Here are some additional tips to help ensure communication isn’t a barrier to contribution:
- Establish a clear code of conduct. This sets expectations for behavior among a project’s participants and protects both the maintainer and all other community members. Your code of conduct lays the foundation for how contributors are supposed to communicate with one another, so make sure this document conveys clear expectations.
- Create a CONTRIBUTING file. This explains what types of contributions are needed and how the process works.
- Take the time to develop a good README file. A README is like the manual of the project and it’s the first file GitHub or any Git hosting site will show when someone opens your repository. It’s also the first file a new contributor should read when starting a new project, so it’s important to make a meaningful README in order to help set the tone for a new contributor. The README should describe the project, include images, define common abbreviations/acronyms used, etc.
- Create good good-first issues to attract more contributors to your project. A good-first issue is a GitHub issue or pull request that has been marked by its creator as appropriate for beginners. This low-hanging fruit helps attract contributors who are new to your specific project — and to open source in general — who might otherwise feel excluded and provide them with a more approachable task to start out with.
- Learn how to clearly articulate your project’s high level needs. As a maintainer, you work to understand the skills, resources and individuals that the people on your project need in order to succeed. And while being a maintainer first and foremost means doing detailed engineering work, maintainership is as much a communication task as it is an engineering one.
- Consider accessibility standards and best practices to ensure your content and code can be used by the widest possible audience. Think about accessibility during design, development and maintenance updates so it can be integrated smoothly and bring down the cost point significantly.
Closing Thoughts
The key takeaway: words matter. While words can lay the foundation for great team collaboration they can also create an unnecessary barrier. Communication is the reason why many open source projects are successful, which is why doing it right shouldn’t be optional or a nice-to-have. Rather, clear communication should be built into open source projects up front in order to foster diverse, collaborative and inclusive communities that move technology forward and lower barriers to participation. Share your experiences and any tips you have for improving communication within the open source community in the comments below.
