Beginner’s guide to contributing to open source through documentation

When starting out in some tech careers, open source is an absolute goldmine for moving from a beginner to an intermediate or expert level, and I wish someone had told me this sooner. Congratulations if you are a beginner who came across this article while looking for answers on how to contribute to open source or getting hands-on experience while learning.

When starting a tech career, as you are learning, it is easy to get lost in something called "tutorial hell," where you read or watch tutorials non-stop without putting what you have learned into practice. You can waste time without getting any feedback regarding what you should improve or where you should improve.

An open source project can help you practice what you've learned over time by participating in projects that require the skills you already have, whether you're starting as a software developer, technical writer, UI/UX designer, or any other tech-related field.

However, a general misconception about open source, especially among beginners, is you can only contribute to open source by writing codes. This is false, as you can make contributions through documentation and designs.

Open source projects, like any other, go through various stages of development. Different open source projects are built with varying programming languages, and it necessarily requires designs to achieve a well-structured format and documentation for users to understand and use the project effectively.

In this article, you will learn how to find open source projects and how to contribute to them through documentation using the AsynAPI website repository as a use case. You will understand the following:

1. Definition of open source.
2. How to find open source projects.
3. How to pick document-related issues to contribute to.
4. How to fork and clone open source projects.
5. How to make contributions.
6. How to create a pull request after contributing.

Prerequisites.

1. Basic usage knowledge of vscode (or any editor of choice).
2. Knowledge of git.
3. Basic knowledge of GitHub.
4. Knowledge of markdown syntax.

Definition of open source

Open source refers to any project that is publicly available for contribution, use, modification, and distribution. Open source has a codebase that is available for anyone, no matter their location, to see, modify, and enhance. Some firms develop open source projects for important factors like collaboration, adoption, speedy advancement, and transparency.

Anyone with a Github profile can access the codebase of an open source project, and it’s not limited to being an expert. This gives a beginner advantage to work on projects while they are learning. Even though open source projects are free and simple to access, this does not imply that all software built on open source is free to use.

How to find open source Projects

A good example is the AsyncAPI website project. AsyncAPI website is an open source project that is built using Nextjs and deployed on Netlify. This website is built to help users understand the AsyncAPI tools.

Here is a list of places to look when searching for open source projects.

1. Google Search: As the saying goes, "Google has an answer for everything," you can search for available open source projects using the Google search feature on your browser. As a beginner, you can tailor your search to open source projects for beginners using the “Beginner” keyword to optimize your search. Google would provide you with articles that have been written over time about open source and available projects.

2. Twitter: Twitter is another goldmine to search for active open source projects asides from being an abode for techies. Using the Twitter search option can help you reach people, topics which may include projects and the latest information about open source. Following this topic and people gives you quick access to updates on new open source projects and what is happening in the open source community.

3. Github search and explore: Github is another place to search for open source projects and almost like the most perfect. it is easier to search for issues to contribute to after choosing a project to contribute to. You can use the search in the left corner on GitHub or the explore feature to look for topics related to open source.

Pick document-related issues in a GitHub repository

After selecting an open source project to contribute to, the next step is to select an issue, and because you are dealing with document-related issues, you will learn what to look for in the list of issues. Let's go over the steps for selecting an issue to contribute to.

1. Navigate to issues on the open source repository.
   

2. Check out and read contributing guidelines to avoid making mistakes while contributing.
   

3. Look for issues that have tags, including docs. Notice how other issues carry tags like enhancement and javascript? These are code-related issues.
   

4. Open and comment on the issue to know if it is still available to be contributed to.
   

once the maintainer replies that it is available to be contributed to; the next is to fork and clone the project.

Fork and clone the open source project

Now that you have picked an issue, it’s time to fork the project into your personal repository and clone it to your local machine.

1. Forking the repo: Navigate to the right corner of the project repository and click Fork
   
   it replicates the project repository into your personal repository

2. Clone the repo: Navigate to your personal repository on GitHub where the project is now copied. Navigate to the right-top corner and click on Clone
   

Make your contributions

1. After cloning your repository, open up the project on your local machine (PC) using the vscode editor or your preferred editor.
   

2. Make your contributions as described in the issue you selected, and add them by using the code snippet

   git add .

3. Create a branch for your changes

   git checkout -b newchanges

4. Add a commit message to your changes before pushing

   git commit -m "I just worked on issue #12345”

5. Push your changes to the project repository

   git push set upstream origin --newchanges

Create a pull request after making a contribution

After pushing your contributions, the last thing to do is to create a pull request. A pull request is a request asking the project maintainer to check and merge your contribution into the project codebase. If the project is successfully merged, you have made your first contribution to open source.

To create a pull request

1. Navigate to GitHub and into your forked project repository, click on compare and pull request.
   

2. After clicking on the compare and pull request, click on create a pull request on the next screen.

This is the final step. Maintainers get notified of your created pull request and go ahead to merge it once it satisfies all requirements.

Conclusion

In this article, you learned how to contribute to open source through documentation as a beginner, how to search for them, identify them and push your contributions. After you push your changes, project maintainers may leave comments on your pull request requesting more changes or additional modifications. If you're confused by the comments or don't understand the requirements, don't be afraid to ask questions; this is another benefit of open source.

It provides you with more knowledge and clarity, as well as an excellent opportunity to learn something new. If you have any questions or need clarification on how to contribute to open source, you can connect with me on Twitter | LinkedIn | or Github. See you in my next article, cheers.