Write the Docs: A guide to getting started in open source – Abigail McCarthy

This talk at Write the Docs Portland 2021 was given by Abigail McCarthy. She provided some guidelines for how newcomers can get started in the open source community and start contributing to their first projects. 

Abigail had been working as a technical writer on commercial projects before she first got involved in open space. She remembered how challenging the new terms, technologies, and different ways of doing things were, and wanted to provide guidance to beginners facing the same challenges.

Understanding open source

Abigail began her talk with an introduction to open source overall. Open source software is designed to be publicly accessible in every way. The common structure is volunteer-driven although there are some paid full-time positions like Abigail's.

Abigail shared three terms used in open source that may require some translation:

• The community describes folks who are interested in the project, but it also describes open source in general – anyone can be involved, can have a say, and have ownership of the project. 
• A contributor is someone who actively participates in the project, contributing code and documentation. 
• A maintainer is someone who is a project leader, with the permissions to merge code changes. When you first get involved in a project it's good to find out who the maintainers are. 

Why you should get involved

Abigail then provided some arguments about why you should want to get involved in the open source community.

Help is always needed

First and foremost, open source projects are always looking for documentation help. A lot of projects might not have had a person fully dedicated to documentation, and the docs might be written by developers. Projects are usually excited to be offered technical writing help. 

Build your portfolio & skillset

Working in open source can have some professional benefits, too. You can build out your portfolio so you have more samples to provide when applying for a job. You’ll learn new skills that can help you transition to a new position.

Broaden your network

Working in open source is a great chance to work with other writers who have more experience. Not only will you benefit from learning from these writers, but it increases your job-hunting network and potential reference pool. Abigail's last few jobs were gained through referrals from her open source network, for example!

How to get involved in open source

Once you've decided to get involved, the next step is figuring out how to do it. Luckily, Abigail has some advice:

Define your expectations

You should know what you want to get out of the experience. Open source is vast with a lot of different projects and opportunities. You can hone in on the types of projects you want to help and the types of contributions you want to make. 

Do your research

Research the projects you are interested in and make sure it’s a culture fit. Finding an open source project is a bit like finding a job, so you need to make sure the project fits in with your values and how you want to work. 

Look for institutional support

You don't necessarily have to go it alone. Utilize company policies or manager support to help you start work in open source. Many companies actively want to support open source projects. You’ll otherwise need to spend your own free time working in open source. 

Look for active projects

Not all projects are created equal. When researching a project, look at the recent contributions and activity for a project. See how many issues have been opened and if people are responding to questions within a reasonable amount of time. You’ll get an idea of how active the community and maintainers are. You don’t want to get too involved in a project that has been abandoned. 

Review project/community expectations

See if the project has meetings, or a Slack workspace, or a mailing list, to get a better sense of how the community interacts with each other. 

The project might have a Code of Conduct that tells you the expectations for the community members and how they should behave. There might be contributing guides that tell you more about the project and how to get set up. 

What you need to learn

The question on any newcomer's mind is how much knowledge you need to have before you can start in open source. As Abigail warns, not all open source projects are set up to handle new or inexperienced contributors. This doesn’t mean the project isn’t worth contributing to but you might have to make more of an investment to get started. 

You might have to get familiar with some new tools, which can include:

• Git and GitHub, which are essential
• Text editors like VSCode, Sublime and Atom
• Markdown 
• Static Site Generators (SSGs) like Hugo, Jekyll and Gatsby. SSGs are lightweight ways of building websites, taking the Markdown files and then rendering the HTML used for the website. SSGs are themselves open source projects and you can contribute to them.

Abigail reassures us: don’t worry about being an expert. All you need is a basic understanding of the general terms used within the tool. 

When you find a project to work on, make sure you read the docs first. Review the open issues that might be labelled as “Good first issue” or “Help wanted”. The labels might be different depending on the project. Join in on project meetings in Slack, and introduce yourself explaining how you want to contribute. Do not be afraid to ask for help. 

Final remarks

Abigail's final advice was largely about being realistic about what you have time for:

• Start small with your contributions and be honest about the time you can commit to the project.
• Be wary of over-committing to things. 
• You can try more than one project, especially if one doesn’t work out as expected. 

As Abigail noted: just get out there and do it. Everyone is there for the betterment of the project. We would add: open source projects can be a space where your contributions are deeply valued, and can be a great way to familiarize yourself with new tools or technologies!

Watch the full talk here.