It all started with Neopets for me. My best friend and I would spend sweltering summer afternoons in her basement writing HTML and CSS and sharing the new colors and effects we found to make pretty pet pages. We used blink tags a lot. Without even knowing it, or thinking of it as coding, we stumbled into the world of collaborative software. I returned to that world my senior year of high school as I deployed my first Apache server, then again the next year when I found the Linux Users Group of Oregon State University at a “Cookies and Clubs” event during my first week of college. OSS has enabled and empowered me as a software user and creator for as long as I’ve been using computers, as it’s done for countless others before and after me. But not every open-source story is a love story.
Users and contributors often face a number of barriers to participating in open-source projects, from confusion about how to get help to frustration when their questions go weeks without an answer. The beating heart of any open-source project is the community, and, as with any group of humans, communication is a key part of helping that community thrive. There are a number of common mistakes I see open-source projects make, which can be remedied with minimal effort and which will make your project much easier and more enjoyable to work with.
I’m going to assume you’ve got the basics of open-sourcing down: You have a contributing guide, you have an up-to-date README, and you have installation documentation that works. Here, I’ll focus on three more practices that open-source projects should enact to improve project interactions.
Establish a Code of Conduct
The first essential element is an enforced code of conduct. We’re all intimately familiar with READMEs—how could your project exist without one?—and most of us have read a handful of contributing docs as well. Codes of conduct are less ubiquitous, yet they are just as important. A code of conduct sets the tone for how participants can expect to interact with your project and gets everyone on the same page about what is and isn’t okay.
The code of conduct may look different depending on the project type, the audience you expect to interact with, and the norms of the project community. It may also change over time as the project grows and new interactions or expectations arise. While each code of conduct is unique, I highly recommend using an existing one as your base and modifying it as needed. This prevents you from leaving out important clauses, ensures that the language is clear, and avoids reinventing the wheel. Mozilla’s Community Participation Guidelines are a fantastic example if you’re not sure where to start, and Geek Feminism’s conference code of conduct is great if you’re hosting an event.
Getting a document in place is relatively easy, but enforcing it can be difficult. It can be awkward to tell a person—sometimes a frequent contributor—that they’ve violated the code of conduct and need to change their behavior or apologize. It requires a tough conversation that isn’t always well received. In my experience, being compassionate but firm is best. You can start the conversation with something like:
Hi X,
The comment “What do you know, you’re just a junior developer” violates our code of conduct because it’s disrespectful and excludes Y from the community. Please remove it and refrain from posting similar comments in the future.
If you refuse to remove the comment or the behavior continues, we will ask you to stop interacting with the project and remove you from the collaborators list. Thank you.
This response includes three key components:
Describe what the person did (with a link to the interaction or logs, if possible) and how that violates the code of conduct.
Explain what they can do to make amends.
Outline the consequences if the behavior continues.
This response neither escalates the situation nor makes value judgments about the person commenting. Stay factual when discussing violations. Your goal is not to alienate the person or make them defensive, but to work together to create a community where everyone feels welcome.
It may also be appropriate to include the person or people harmed by the comment in your enforcement communication so that they can be part of the conversation and so that the person who violated the code of conduct can apologize directly. However, this really depends on the social dynamics of the situation. Always ensure that the person or people who have been harmed are okay with being included on the enforcement communication before it is sent.
An enforced code of conduct will help make your open-source community a more welcoming and friendly place. It will also help ensure that all users are being respectful and kind. Creating a positive environment in which your project can thrive allows both new and veteran users to better use and contribute to the project. A good code of conduct is like a hard-drive backup: Hopefully you’ll never need it but, if you do, you’ll be glad to have one.
Publish contact information
Many open-source projects also lack clear instructions for asking questions and submitting issues. Contact info often takes the form of a GitHub account or email address listed at the bottom of a lengthy README or contributing doc, which is just bad news bears. Sending an email is intimate and direct, and means that only one person can answer the question. It also means that others with the same question won’t be able to find the answer. Two issues are at play here:
You need a unified platform for interacting with your community.
You need to clearly publish your contact information.
Let’s talk about community platforms. A good way to think about where to build a community is to examine the platforms you already use. You’ll be most available and have the most success answering questions if you draw people to a place where you already spend time, whether it’s Twitter, Reddit, Slack, Stack Overflow, etc. It’s also best to choose a platform that’s easy for others to join. If it’s a more obscure platform, include directions for setting it up (for example, link to a guide to joining Mastodon). As long as you’re there, your people will find you. I’m of the opinion that it doesn’t ultimately matter where your community gathers, so long as it’s the best solution for your project. For example, the best way to contact the leaders of SeaGL is on Internet Relay Chat (IRC), not because IRC is the best chat client out there but because that’s where the community leaders hang out. As such, it’s the very first option listed on their contact page.
I recommend most projects choose just two to three platforms: one for creating and tracking issues, and one or two for community discussion and questions (or “structured” and “unstructured” platforms, as Jono Bacon has labeled them). Having too many platforms makes it difficult to find a particular discussion or issue and can lead to communication chaos. Conversely, having just one platform serve as your issue tracker and community discussion platform is like forcing a screwdriver to also be a hammer.
The platform where your project is hosted most likely has a built-in issue tracker (e.g., GitHub issues), which allows the community to submit issues or ask more structured questions. It’s helpful to outline in your contributing doc what structure these issues should have and, if possible, provide a template so that users are essentially filling out a form when creating a new one.
The chat platform you choose should be one you check regularly, at least once per weekday. Slack works great for the Bolt project because it’s the platform we use for work at Puppet and it has a lot of features (threads, emojis, polls, etc.). Many projects use IRC as a free alternative.
Once you’ve determined what your platforms are, shout them to the world! Your contact information should be the first thing in your contributing doc and should be placed toward the top of your README. If you have documentation hosted outside your project, make sure you’ve got a contact page there, too. I get frustrated when I’m forced to spend five minutes searching for the appropriate forum to ask a question about a project only to end up tweeting at the maintainers, asking a question in an empty IRC channel, or creating a GitHub issue for something that belongs on a chat platform. None of these is a great first experience. Don’t let it happen to your project!
The next part is harder: Once you’ve published your contact protocols, you must hold up your end of the conversation.
Be available to help
I offer an immediate caveat to this recommendation: I don’t mean be available all the time. I’m a firm believer in work-life balance, and technologists in general err on the side of being too available. However, I see so many people open a GitHub issue or post in IRC, on Slack, or on mailing lists to radio silence. No one will even acknowledge that they asked a question for months, until a kind user who has run into the same issue posts the solution or says they’ve had the same problem. This is deeply disheartening to new users and can make a project unusable.
Sometimes the issue is that the project is inactive, but if you’re reading this, your project likely has someone at the helm— possibly you! It’s that person’s responsibility to either be the project’s responder or to delegate that role to someone else. Then they must ensure that they’re available on the platforms where they say they’re available. Aside from the aforementioned lack of designated responders, the silent treatment often happens because project leaders either don’t know how to answer the question, don’t have time to answer, or just never see it.
Depending on the size of your project, it may be appropriate to establish community interaction as part of team responsibilities. For Bolt, we’ve found that certain people are topic experts, resulting in advice like “Ping Zed for Windows questions.” Others are available at different times of day: One is on duty very early in the morning while another handles a later shift. We also have published weekly office hours when folks know that maintainers will be online to answer questions. This mishmash system is just one example, but in it everyone knows when they need to be online, and responsibility is delegated to minimize fatigue or burnout.
Once you know who is to be online when, be online. Set up alerts to be notified when there’s a new post on your platform. Acknowledge that someone asked a question, even if all you say is “I don’t know the answer, but I’ll try to find out or ask the right person and will let you know.” Even “I’m a bit busy, but will respond shortly if someone hasn’t already” is better than nothing. (Then, of course, remember to respond.) I set up a notification when a new query arrives and only “resolve” it after I’ve responded. You could also set an alarm, ask someone else to respond, make a habit of checking back hourly, even write it on your arm—whatever you gotta do. Your goal is to make the user feel heard. It’s obviously helpful to answer the question as well, but if for whatever reason you can’t, that’s okay. Just acknowledging that you’ve seen the question and that you will try to answer, resolve, or escalate it is a job well done.
There’s a place for everyone
Open-source projects are, in so many ways, like Neopets: With an available owner, useful contact info, and a thorough code of conduct, they will thrive. Okay, that metaphor may have broken down a bit. But OSS projects are like Neopets in that they need diligent care, are similar but unique, and are so rewarding if you put the work in. Your project doesn’t need a huge overhaul, a massive ad campaign, or perfect code to be awesome. It’s already awesome if you’re able to connect with humans all over the world and empower them through technology. And when you communicate effectively with your community, it will be so much easier for everyone to use. So feed your JubJub, get yourself a code of conduct, and go kick ass!