Want to improve diversity in tech? We need to start with including everyone.
In this post, the second post in a series of two posts based on the presentation I gave at Ruby on Ales 2016 called “Including People” (watch), I share five things you can do to include people in projects, teams, and communities. Earlier, I talked about why including people is important.
While this post is about all projects and teams, open source projects happen to be public, so it’s easy to talk about them and use them as examples. Over the last six years of working on Bundler, I’ve seen (and sometimes experienced) the ways that tech and open source are exclusive. We can do better.
I’m not anywhere close to an expert at including people, but I have (sometimes painfully) learned a lot of ways to exclude people. I’m going to tell you about them, and then tell you about how to avoid them! That’s not the end of inclusiveness, but it’s a good start.
1. Remember people are why you are here.
Software is made by people for use by people. Keep that in mind while you work on it! Projects usually involve three groups of people: end users, potential contributors, and the existing team. It’s easy to be inclusive towards one of these groups while still being hostile to other groups. In the Linux kernel, for example, end users are welcomed and documentation is provided for them. Contributors, on the other hand, are semi-regularly told that they are brainless imbeciles (or even worse language). Not so good on the welcoming, there.
2. Include your users.
So, let’s start with end users. How can you be welcoming and inclusive of the people who use the software you work on? There are a lot of ways. People who are interested in using your software will pay attention to the other people working on it. They will pay attention to the other people using it. They will pay attention to whether your docs only ever say “he.” They will notice if reporting an error gets the response “that’s stupid.” So here are some straightforward ways to make sure that people using the code you write feel included.
Establish and enforce codes of conduct.
The most straightforward way to include people who are interested in your project is to establish a code of conduct, and then enforce it. At this point, there are a lot of examples of projects that have a code of conduct. Bundler is one, the Rust programming language is one. Coraline Ada Ehmke has even created a template called the Contributor Covenant that any project can use.
A code of conduct makes it clear that the project intends to provide a safe space for users and contributors that is free from harassment. Without one, anyone who experiences harassment on the Internet will be much less likely to become involved in your project. That would be a tragedy, because most people who aren’t white Caucasian males on the Internet experience at least some harassment.
Closely related: IRC channels, Slack rooms, emails, and Twitter. Don’t just follow the code of conduct in all of those places, make sure that the code of conduct is being followed by others. Anyone that you have allowed to officially represent your project, whether core team or just a contributor, needs to understand that harassment and condescension is not okay. Listen and speak respectfully. Follow the code of conduct yourself, and call out anyone who doesn’t.
Finally, and this is true for every project: you have to enforce the code of conduct with everyone, whether user, contributor, core member, or yourself. If you have a code of conduct but let people slide, your project will become known as not just hostile, but hypocritically hostile.
Write great documentation.
Next up, documentation. It’s a thing. You probably don’t have as much as you think you should, and chances are high you’re embarrassed about it. That’s okay. I work on a lot of projects, and none of them have perfect documentation. The ground rules for helpful, inclusive documentation for end users are pretty straightforward: use “she” or “they” instead of “he,” and write some documentation that is aimed at newcomers to the project. Just that, and nothing else, is enough to get you off to a good start.
You can do better than that, though! For a fantastic explanation of how to write documentation that is genuinely helpful to users, check out the talk Writing Great Documentation by Jacob Kaplan-Moss. He outlines four kinds of documentation that your project needs to be useful to all the people who will look for it.
Tutorials
The first type of documentation is tutorials. Tutorials should explain how to accomplish a specific task. It should be possible to follow them start to finish in 30 minutes or less, and they should link to other tutorials or topic guides whenever they are relevant.
Topic Guides
Next up, topic guides. Topic guides explain a single topic in detail, mentioning the options, details, and unexpected bits that are specific to that topic. Topic guides should refer to other tutorials and topic guides as they’re relevant.
Reference Documentation
Then there’s reference documentation. These are the API docs for your project. They are the most likely to already exist, but they are also completely useless for someone who doesn’t already know what they’re looking for. This is the reason that Rails has both extensive API docs and a guides project full of topic guides.
Troubleshooting Documentation
Finally, troubleshooting documentation. There will be problems that come up again and again—if you can, fix them in your code. If you can’t, add them to the troubleshooting guide. Write down the steps that you suggest to people having problems, and explain exactly what information you will need to be able to help someone who has a problem that they can’t fix on their own. As you write it, keep in mind that the person reading it will be frustrated at minimum and raging at worst. Keep it straightforward, don’t condescend, and try to be helpful.
Give better answers.
Speaking of troubleshooting, how your project handles issue reports is a huge indicator of how inclusive your project is. If you respond to a new issue with “that doesn’t make sense” or “why were trying to do that,” the hostility implicit in those statements will be heard loud and clear. Start with the idea that whatever the reporter is trying to makes sense to them. Then, try to figure out what context they have that you don’t (or that you have that they don’t) that can help solve the issue.
The talk Giving Better Answers, given by Sam Marshall at Alterconf Chicago in 2015, has really great concrete examples of how to give answers that are helpful without being condescending or hostile. Finally, always thank users for taking the time to report the error to you (they didn’t have to!). Always let them know than even if their problem isn’t a bug, you’ll try to help them, or at least suggest somewhere else that they can go to get more help.
3. Include your occasional contributors.
Now let’s talk about how to welcome contributors to your project. Everything that I’ve said so far about welcoming users applies to welcoming contributors, too. A safe environment without harassment is a requirement. Documentation helps a lot. Just having those things, though, isn’t enough. There’s more you can do to encourage contributions to your project.
Ask for help.
First, and I can’t say this enough times, the biggest thing you can do to encourage contributions to your project is to ask for help. (Let me take this moment to say that I run the Bundler project, and we would love to have your help) Most people think that they need to be total experts on something before they can even begin to help.
Let me make it extremely clear: I have never been an expert on any project that I have started to work on. I have also learned more by working on open source projects than any other way that I have learned anything about programming. When you ask for help, and when you write a document explaining how people can contribute, make it clear that they don’t need to be an expert to be able to help you. Schedule times to pair with contributors at any skill level, and then actually pair with them so they can get started.
Document development, too.
Write development documentation. This is completely different from the documentation that targets end users. It needs to explain how to set up the project locally for development and how to run the tests. It needs to explain who runs the project, what policies there are for contributions, and how to contact the other contributors on the project.
Don’t stop there, though. If there is anything you have to do repeatedly, like triaging issues, write a document that explains the steps. Write a list of every type of help you would like to receive. For Bundler, that includes fixing typos, writing docs, triaging tickets, refactoring code, fixing bugs, implementing features, and lots more. We have a dedicated document that not only lists each kind of help we would like to get, but links to guides for that specific type of help.
Treat pull requests the same way you treat issue reports: the person opening the pull request has context that means what they are doing makes sense to them. Even if there is no chance that you will ever accept the PR, thank them for making it (they didn’t have to contribute!). Explain your reasoning. Try to understand the underlying problem that drove them to send the PR, and see if there is a way you can help them even if you aren’t willing to accept the patch. Respect their intelligence and their time, and they’re likely to keep contributing.
4. Include your team.
It’s important to apply all of these principles to your entire team. Respond to code of conduct violations aimed at your team members. Make it clear that you have their back. Tell them that you appreciate their help. Apply the exact same principles that we just discussed for users and contributors: assume that what they are doing makes sense to them, and work to find the context that isn’t shared so that you can understand each other. Finally, give positive feedback and make requests. Collaborate with your team, discuss decisions, and listen to their input.
5. Have respect and empathy.
In the end, everything that I’ve suggested comes from the underlying principle of having respect and empathy for other people. Other people don’t have the context you do, and they don’t have the skills you do. Almost all of the time, they’re just trying to do their job. They can tell when you’re trying to help, and they’ll be very happy to receive that help. On the other hand, they can tell when you don’t like them and don’t care about them, and they will respond to that as well.
Treating others the way that you personally would like to be treated isn’t enough. Listen to people in underrepresented groups. Pay attention to how tech as a field mistreats those underrepresented people, and actively work to fix it. Call out people violating codes of conduct. Let them know that what they’re doing isn’t okay. Tech as a field is biased and exclusive, and the only way it will get better is if all of us act together to change it.
Let me finish by taking one of my own suggestions: I run a popular open source project, Bundler. We want to be more inclusive! The Bundler team has committed to offering pairing time to any developers who are willing to contribute.
I also want to continue to improve these two posts, my talk, and the inclusivity of tech as a field. If you have ever thought about contributing to open source, but felt intimidated or excluded, please let me know about your experiences-—I want to change things so that everyone will feel capable, welcome, and empowered to help make things better.
