Theory: Contributing documentation to your first open source project on Github

I’ve wanted to make my first pull request on GitHub for a long time. I had been held back out of total fear of failure.

I’d used GitHub during a practice project I did in my Ruby on Rails course in 2016 with Code First: Girls – but without the support of the mentors to guide me, I couldn’t move past my fear of contributing to open source.

Until now.

My hurdles with contributing to open source

Other factors contributing to my paralysis was that I had heard terrible things about how unpleasant open source developers could be towards each other – especially total newbies. Especially women.

I’m not even a real developer, Imposter Syndrome whispers in my ear. I can only code a little bit, so I don’t belong.

Another factor was that I couldn’t see the step between my desire to contribute, and what it would actually look like to submit that first pull request.

Many helpful resources have been published that encouraged me to “just get started”. I scoured blog posts that might reveal how to make a pull request. I knew that there was a need for more contributors.

All of these posts were aimed at a more advanced level of technical proficiency than I was at. These posts also focused on using the Git command line rather than the GitHub web interface – usually because most people think that’s an better way to get started with Git (the platform on which GitHub is built).

Contribute to open source on GitHub

In other words, the posts were aimed at developers who are just like the post authors. I would read a post, head over to GitHub, and still be completely stuck.

I would then do nothing, until I got another burst of motivation – and then I would repeat the cycle again.

Why I wanted to write a GitHub open source post

I wanted to write this post to be aimed at the total GitHub novice. This person is someone who has never used GitHub and isn’t a developer, but wants to contribute to an open source project – possibly through documentation.

Why would someone who is not a developer want to contribute to open source?

I always hear that there’s a lack of non-developer skills in the open source community. The truth is, there are already many developers contributing to open source (though not that much diversity). That’s because it’s a great way to build a portfolio as a software engineer.

Open source software is often one of the outputs of a real-life community, run by incredibly nice individuals – take the Python community as an example. FreeCodeCamp is another thriving, global open source community.

It’s true that people can be harsh to each other online, but take it upon yourself to find a positive community that suits your temperament. That way we can all take responsibility for creating a better internet.

Some open source software projects exist purely as communities online, where people don’t tend to meet up in real life. This might better suit people with very little time to spare, find it difficult to travel, or who don’t feel that comfortable in social situations.

Why contribute to open source

You can become involved in any online or hybrid online-offline community. You may want to do so because participation in open source can lead to many other opportunities and helps develop new skills. It’s also really fun.

For example, I’m a freelance writer. I am interested in making the move to becoming a technical writer, and I wanted to gain experience in documenting an open source project. I had been interested in open source for a long time, but I hadn’t directly made the connection with documentation.

An experienced technical writer had suggested the idea of contributing to open source documentation to me, at a conference where there were many opportunities to contribute to different open source documentation projects.

What great timing! A light bulb went on.

It helped to be in a real-life environment where someone friendly could explain the steps I had to go through to contribute.

Write the Docs open source project

The project I picked was Write the Docs meetups team.

The Write the Docs conference is for documentarians to come together to meet new people and learn new things about documentation. It’s closely aligned with software and development, so there are lots of technical talks and activities.

During Writing Day, we all had a chance to join an open source documentation project. One of those projects was the Write the Docs meetup team. They needed some issues dealt with in their documentation. Everyone was really encouraging.

A lot of projects are more developer-focused and may be intimidating to newcomers who aren’t trying to contribute development skills. That’s why I wanted to contribute to Write the Docs, because I was already at their conference in Portland.

They were actively asking for contributions that day.

How you can find an open source project

It might be good for you to attend a workshop or a community event that is specifically geared towards welcoming newcomers to open source. Learn as much as you can on your own first, and then seek out support to help you.

I am co-hosting an upcoming workshop in Manchester during National Coding Week to do just that.

Write the Docs North

Image caption: Write the Docs North meetup spans Bradford, Leeds and Manchester

So find a community where you might be able to have access to some open source groups. There will be frequent opportunities for newcomers to have their induction to open source.

It’s better to start off from a real-life springboard because it can help you overcome that fear of the new. You can connect it to something tangible and meaningful. The energy of everyone else is infectious.

At Write the Docs, I still had to figure out GitHub on my own, but it was the motivation I needed to actually commit. My next two posts deal with:

Get in touch with me if you’re interested in the upcoming workshop at catherine@awaywithwords.co.

About the author

Catherine Heath

Catherine is a freelance writer based in Manchester. Blogs. Copy. Documentation. Let's ditch the jargon – just give her plain writing.

View all posts

Leave a Reply

Your email address will not be published. Required fields are marked *