Contributing to Documentation in Open-Source

Contributing to open-source can be overwhelming.

You are creating a pull request to an open-source project that would open up your code for people to give feedback and criticise.

This turns off a lot of new contributors from making an impact in open-source.

You might also be at a point where you are not confident enough in your programming skills that you hesitate to take that first step in contributing code.

A good way to tackle this and gain confidence to contribute code is to start by contributing to documentation.

Documentation is necessary for every open-source project. Contributing to and maintaining documentation is not an easy task but is highly impactful.

I will drop a bomb and say contributing to documentation is more important than contributing code.

In this post, I will try to share my insights on contributing to documentation from my experience as an open-source contributor and a maintainer.

Being overwhelmed when you first start to contribute to open-source is natural. Start small. But start.

Finding a Project

The first thing to do before you can start contributing is finding a project you can contribute to. And the best project to contribute to is the one you have been using for a while.

That is, if you have been using a framework or a library, a tool or any other open-source project, contribute to it.

With this, you will have a lot of context on what the project is and you will definitely be able to find areas in the documentation you can improve.

If you cannot find such a project to contribute to, look for projects with an active community of contributors.

Community is key in open-source and you will definitely reap the rewards for being part of a thriving community.

All these factors comes secondary to the fact that you should always contribute to projects that YOU are interested in.

Start as a User

As mentioned in the above section, you will be able to make impactful contributions if you are already a user of the project.

So, if you aren't, you should start by exploring the project from the perspective of a user.

As a user, you will likely go through documentation and tutorials as you start out and you are likely to find bugs, out-dated content or things you can improve.

When you find areas to improve, open up issues (or any form of tickets if you are not using GitHub) for these and discuss with a project maintainer to validate it and get it assigned to you.

Once you have been assigned an issue, you can start contributing.

Review the Contributing Guidelines

Most (if not all) open-source projects will have a contributing guideline in their GitHub/GitLab repository.

This document will be geared towards contributors with guidelines on setting up a developer environment and how you can make contributions.

Read these guidelines carefully and make sure that you follow them.

For example, if a project requires you to sign every commit, your pull requests will be rejected very quickly if you do not do it.

What should you Document?

As mentioned in the previous sessions, you are likely to find issues when you start to use the project referring to the documentation.

This could be as simple as an outdated screenshot to outdated or missing documentation.

Open up issues for these as mentioned and discuss it with a maintainer to get it assigned to you.

If you cannot find issues by yourself, you can try to fix already open issues.

There are labels in GitHub issues that can help you filer out only "documentation" or "docs" issues and similar features will be there in any ticketing system being used by the project.

In-Code Documentation

People generally don't think of this when they think about documentation.

In-code documentation refers to the error messages, help texts and other text the user interacts with that doesn't necessarily affect the "logic" of the code.

These are really important as users will definitely interact with this while using the project.

As a new contributor you have the magic eyes to spot issues with these that seasoned contributors are too close to notice.

More Ways to go Beyond the Docs Page

Good documentation is not just limited to the docs page.

It can also involve:

• Writing a blog post that takes the user through a new feature
• Creating a Twitter thread about the project
• Documenting processes that can be used for the community (a contributing guide for example)
• Updating the project's website

You can always ask the project maintainers to help you find areas that need contributions.

Before we finish this, I want to point out that non-code open-source contributions are not just limited to writing documentation.

You can check out other ways you can contribute to open-source projects without contributing code.

Originally published on navendu.me