The importance of good communication should not be underestimated — it’s listed as a desirable skill on almost every job posting. Technical or non-technical, communication skills are critical for building trusted, productive relationships. But even if you have “excellent communication skills” listed on your LinkedIn profile and fancy yourself a clear communicator, you may want to rethink what that actually means, especially when it comes to software development and open source.
Open source is built on the premise of community. A project started in open source is a real-time example of collaborative innovation. But collaboration can only happen if there’s a community. And, it’s impossible to separate community from communication. From a language origin perspective, the words enjoy a common Latin root: communis, meaning common.
In open source, communication takes many forms: from meetups and chat rooms to README files, demo instructions, code of conduct, even pull requests and commit messages. All of these elements form the project’s “communication” to the community and informs and teaches potential users and contributors about the project. If your community is small, dwindling or lacks enthusiasm or fresh ideas, maybe it’s time to take a second look at your communication.
So, where should you start looking for opportunities to improve your communication? Documentation is probably the first thing to come to mind – and it’s a great place to start. Survey after survey reveals that developers cherish great documentation (the most formal of all project communication) above all else. Documentation is the entry point to new technology, but it’s only the very first step.
Beyond documentation, there are the words you use and how, where and when you use them and in what form: written, spoken, in code or in commits. Let’s take a quick tour and look at some specific examples, starting with the secret languages used by many open source communities and projects.
Speaking in Code
The world of open source is often infused with a vibrant “language” beyond the code itself, full of acronyms, unique phrases and clever inside jokes. But this secret language can erect an unnecessary and often impenetrable barrier for new people to use a project or join its community.
Think about a moment when you walked up to a group of colleagues only to find that you had no idea what they were talking about, and consequently had nothing to contribute to the conversation. The same concept applies here. Some of the terminology used in an open source project could make new community members — coding veterans, contributors and maintainers from other projects — feel alienated and discourage them from participating. Without clear, welcoming language you’ll limit the community talent pool to the few who understand the internal “language” or vocabulary. Limiting the talent pool can make it more difficult to diversify and increase the team working on your project. And less diversity likely means you’re missing out on new ideas that could help the project grow.
How to fix this? Have a colleague or other industry peer review your README file or your Contributors guide. Give them a five-minute description of your project. Do their eyes light up or do they look back in confusion? Tap a sympathetic technical writer for a 20-minute assessment of your project’s key documentation. You’ll be surprised by what you discover.
Two North Stars: Respect and Inclusivity
Concerning word choice, be thoughtful with inclusivity and respect as your North Stars. Unfortunately, the old saying “Sticks and stones can break my bones but words can never hurt me” just isn’t true. Words matter and can put up barriers, making people feel unwelcome.
This year, for example, we witnessed many brands forgoing their historical yet controversial mascots that were rooted in the Jim Crow era. Likewise, GitHub recently abandoned its decades-old coding term “master” (meaning the main version of code) to the more neutral term “main” to remove references of slavery. When asked about updating this terminology, Google Chrome developer Una Kravets stated, “If [this language] prevents even a single black person from feeling more isolated in the tech community, feels like a no-brainer to me.”
In an effort to remove harmful, racist and unclear language in software development and unify the adoption of replacement terms across the industry, the Cloud Native Computing Foundation recently launched the Inclusive Language Initiative. The long-term goal of the initiative is to remove all harmful and unclear language of any kind and replace it with an agreed-upon set of neutral terms, preventing developers from feeling alienated or confused as they embark on new open source journeys.
VMware’s Stephen Augustus is part of the group exploring alternatives and devising best practices. When words, symbols or other elements of language are controversial or have negative connotations, they can quickly deter people from wanting to get involved in your project.
“I have always believed organizations should prioritize people, processes and then tools. In the case of the Inclusive Naming Initiative, this means getting the right people involved to have critical discussions, then developing appropriate processes to get this work done.”
If you’re looking to include more people and grow your user base, look at your language. Think about your project’s name, too. A seemingly innocent word or phrase can possess alternate and sometimes derogatory meanings. Do your research!
Software for Everyone: Eliminating Accessibility Barriers
Communication can exclude another important audience of users and contributors: those with accessibility challenges. In its 2020 annual survey, WebAIM found that of the top 1 million websites, less than 2% of them were completely usable by people with disabilities using assistive technology such as magnification, screen-readers and voice-to-text software. While your documentation, files, etc. might be well-written and well-intended, they may not be accessible to all. Communication extends not only to the words you choose, but also how you convey those words on the screen both in format and design, documentation and code. For more on accessibility challenges and some steps to address it, learn from VMware’s Sheri Byrne-Haber, an Accessibility Architect and leader of the recently announced open source project, Crest. Crest aims to make checking for accessibility more automatic and less time consuming – leading to better software for everyone.
In the next installment, we’ll take a look at some of the mechanics of an open source project and identify some specific areas where improvements can make a significant dent in your communication “score.”
Follow us on Twitter (@vmwopensource) for all the latest open source news and updates.
