Open Open Source

By day, I'm a developer for Marks & Spencer Digital. Any other time, my work is within the Open Source community. I'm a core member of Hoodie and a member of the Node.js inclusivity Working Group. I'm also the creator of Your First PR, an initiative to get folk interested in Open Source.

I've said the term 'Open Source' a couple times now and it's time for me to explain what that means. The cool folk over at opensource.org define 'Open Source' as:

software that can be freely used, changed, and shared (in modified or unmodified form) by anyone

To illustrate this a little further; imagine I had just built a Pokédex. It lists all my favourite Pokémon. I can share this list by putting my code online and sending you a link to myfavouritepokemon.com. But, I don't want to show it to anyone right now as it needs a lot of improvement and I could use some help.

I can put my code online somewhere like GitHub which is a tool for hosting and working on code. I can then point a friend to my code and they can join the project and start making improvements with me. Other people can copy my code and make their own Pokédexes, too, as long as I give them the license to do so.

Many things run on Open Source software. Linux is used on most servers, in most businesses. Linus Torvalds created Linux, but it would be little without the thousands of developers that help.

This post is about the first word within the term 'Open Source'. 'Open'. Although the definition says that Open Source software can be freely used, changed and share by anyone; in practice, I disagree.

When we look at the biggest contributors to Open Source, we see that they have resources that others may not. Such as time, energy, a decent internet connection, little experience of harassment, support from a workplace, or just a job at all. Open Source is best at catering for the folk who have access to these resources.

That needs to change. I'm going to go through things that I believe we can do to make our Open Source communities more open. So that we can offer a greater experience, help folk to learn, and improve the quality of our projects.

This is not a post where you will get a golden solution to the problems endemic in Open Source. But I intend to help you get started.

First on the list is one of the most important things you can do to make your project more welcoming. It's time to get a Code of Conduct.

Codes of Conduct

If you have an Open Source project somewhere in this magical universe, you should have a Code of Conduct. Even if it's just you working on the project right now.

A Code of Conduct is an outline of what is and isn't acceptable behaviour in the realm of your project. It should outline the responsibilities of maintainers to ensure contributors keep to the code. It should also discuss what will be done if the rules are broken.

The concept of a 'Code of Conduct' is a controversial one. Its purpose is to ensure that no-one in the project is subject to bad behaviour. But, there are several popular projects that have decided not to adopt one, often under the guise of 'free speech'.

A Code of Conduct does not mean you will not have a negative experience within the project. It is a pledge by the project creators that they will try their hardest to ensure it does not happen.

I feel more comfortable dealing with Open Source projects with Codes of Conducts as it feels like the project cares about my experience.

My favourite Code of Conduct is the Contributor Convenant, created by Coraline Ada Ehmke. It defines what will not be tolerated, and outlines what will be done should the rules be broken.

So should you use a Code of Conduct? Yes. But slow down. You shouldn't just copy and paste something into a markdown file. Explore popular Open Source projects and see what they use. If you do use a pre-written one, read it through in detail as it's important you know what you are pledging.

If using a template like the Contributor Convenant, make sure to check regularly for updates. If you're not keeping it updated, it shows others you don't care about it, even if you do.

Most importantly, you have to be prepared to deal with problematic behaviour. It is less harmful to not have a Code of Conduct than to have one that you don't enforce.

If you want to know more about Codes of Conduct, check out Ashe Drydens' awesome 101 + FAQ.

Readme's

Another document important for your project is the first one everyone sees, the Readme. This is the first page displayed when someone comes to take a look at your project.

The Readme is what can convince someone to use your project. You might say how amazing it is to use Unicorn.js, how easy it is to install and then will provide instructions on how to use it:

Install Node.js

npm install Unicorn

This is a good start, but we're only just beginning. Where do people go if they need help? What are some common questions that you can answer? Do you have any examples of how to use your thing? Are there any upcoming features you'd like help with?

A Readme is a good way to answer common questions. This helps the person using your tool and it'll decrease duplicate questions in the issue tracker.

My perfect README contains the following:

  • Project Title

  • Short description of project, including link to Code of Conduct

  • How to install the project

  • Link to tutorials and code examples

  • Frequently asked questions

  • Where to ask questions, i.e file an issue

  • Link to any issues that the project needs help on, like upcoming features.

  • How to get in touch with project maintainers, including more private communication

The Readme is also a great place to ask for help. If you showcase the issues you're working on then you're more likely to attract people who want to work on them. Which brings me to the next awesome thing you can do for your project.

Github Issues

As mentioned in the beginning, I'm the creator of Your First PR. Your First PR is a twitter account that posts GitHub issues that I believe to be approachable for a beginner to programming or open source. To post these issues, I need to encourage y'all to write good ones.

When you're learning to program or learning a new technology, a good place to go is the Open Source community. Working with real people on real things is a great way to learn. Preparing starter issues creates a positive attitude of learning and sharing within your project.

So, what makes a good GitHub issue? Here's one I prepared some time ago.

Hoodie Github Issue

Title: [Accessibility] Give the Hoodie Logo meaningful alternative text

Starting with the title, the first thing we see is the word 'Accessibility', so we already know the subject matter. I then go on to explain the solution rather than the problem. When you read the title, even if you don't know how to do it, you know what the solution is.

I then go into more detail about the problem, providing a way to replicate the accessibility bug using a screenreader. Next, I provide step by step instructions on how to solve the issue; giving line by line changes to make. I also provide the commit message to use, to follow project conventions. If the issue solver gets stuck, I tell them how they can reach out to me.

Labels: bug, help wanted, starter

Make good use of labels. These are the things people will use to find the kind of issues they are looking for. 'bug' indicates that it is something that needs to be fixed rather than a new feature implementation. Bugs are more approachable for beginners as they don't need to do something from scratch. 'help wanted' vocalises that we do actually want someone to submit a pull request for this. 'starter' is the tag we use at Hoodie to show that this is a good first issue for a new contributor. Try to pick one label for this.

Inclusive Language

To do the above three things well, we need to get our language right. By using inclusive language, we engage with more people and make them feel more welcome.

As a general rule, I make sure that I use few complex words when describing a project. Just because we know fancy long words, doesn't mean we have to use them. The ace folk at GDS recommend that we write for an audience of around 9 years old. Using apps like Hemingway Editor we can ensure our writing is straightforward and understood.

As tech is dominated by men, you'll see a lot of examples that talk about "him" and "he" because the writer is often writing for themselves first. To combat that, folk made an effort to use "she" and "her" in their examples. I use neither. Use gender neutral language: the world is not just made up of "hims" and "hers" and it's important to recognise this. Try to use "they" and "them" to describe people in your documentation.

Avoid using phrases like "hey guys" or "you guys". It's likely that not everyone in the group you're addressing is a "guy". Try words like "folk", "y'all", "everyone".

Words are hard and you can't change the phrases you use over night. In the Hoodie Slack, we've programmed Slack Bot to call us out when we use "bad" language. For example if I say "guys" it would say something like "I think you mean friends...".

Slack bot

If you want to do the same in your Slack channel, my Hoodie colleague Stephan compiled a list of words and alternative phrases.

Some other words I would avoid using are "simple", "easy" and "just". If someone struggles with a thing that's supposed to be "easy", they will feel demoralised. What is easy to me isn't necessarily easy to you and vice versa.

Code is not important

Chances are that your open source project is code based (not the only use for something like GitHub). You have a JavaScript Framework full of nice cool modules, a website and a CLI tool to boot. All which is Open Source code, so you have a lot of programmers on your team.

But, how do you communicate to the outside world? Who writes your newsletter? Who does your illustrations, logos, graphics? Who moderates the Slack, IRC or Gitter channels? Code is a small part of your project.

At Hoodie we have an editorial team. The people who manage our newsletters, our blog posts, our twitter account and more. They are the ones that help us update the team to goings on and make sure we're doing all we can to provide a welcoming and informative environment for contributors.

There are lots of people out there who don't want to contribute code, but there are other important ways to get involved. By paying more attention to these things and including them in your plans, you will open up the doors to a variety of talented people.

Community Engagement

Tying in to this, we can now talk about community engagement. The community is what makes your Open Source project and it's important to recognise them.

If your project is the kind to do official releases, write good release notes. Not only is it good way to inform folk about your shiny new features, it's also a good way to let people know of any breaking changes. On top of that, you could write a blog post about your release that goes into more detail. Provide examples of how to use new features and thank the people who contributed to the release.

Have a place where past, current and future contributors can hang out with the larger community. Whether it's IRC, Slack, Gitter or something else; make sure some of the team are somewhat active. If you're not around to answer questions, the channel becomes inactive.

Twitter seems to be the tool of choice for the technology industry. People can take it in turns managing your official account. It's another way in which you can share news, answer questions and thank first time contributors.

Other things you can do is have a forum or write a newsletter to update subscribers. Have an official project email account where people can ask questions privately. Hold events to work on the codebase together, help new contributors and teach people to use your project. Answer questions related to your project on Stack Overflow.

Recognise your limitations

Last but not least, I want to talk about you. Open Source is fun, and we usually get consumed by fun things.

To do our best work, we need to recognise that we need time and space to do it. You will not survive if you do a 9 to 5 and then come home to do Open Source every evening and weekends. Speaking from experience, you will burn out.

You also need to recognise that your team cannot be available 24/7. Sometimes deadlines will be missed, things will take longer than expected. Life gets in the way: people get sick, people live in places with crappy internet connections, people wake up and just don't want to do work that day. You need to be supportive of this, otherwise you will drag yourself and your team into the ground.


Open Source is huge, fun and full of challenges. By taking aboard some of things I have said today, you can turn Open Source into something even better. To be truly open you need to consider people. Without people, there is no open source.

-->