Contributing to open source can be a daunting prospect, especially if you haven't done so before, or if you're used to working on documentation rather than code.
This guide will help technical writers get started contributing to open-source projects, and outline some of the common pitfalls you might encounter when starting to contribute.
It'll also highlight some of the benefits of contributing to open source, and provide some additional resources for getting started with contributing to open source as a technical writer.
What You Will Learn
This post will cover how technical writers can contribute to open source, what the benefits are, and some of the potential drawbacks. We'll also go over a few resources for getting started.
What is Open Source?
Open source is a collaborative way of developing and distributing software. People all over the world contribute to open-source projects by adding features, fixing bugs, answering questions, translating text, or writing tutorials.
Why Contribute?
Contributing to open-source software is one of the best ways for technical writers and other knowledge workers to give back and make a difference.
You can help improve the software you use every day, or you can learn from the example of others who have contributed before you. Plus, it's a great way to meet people with common interests. And when your contributions are appreciated, you'll feel like part of the community.
You might be wondering – when should you contribute? Well, if you're new to open source, contribute at your own pace—don't worry about trying to do too much too soon. You'll find what you're comfortable with.
Contributing to open-source will not only increase your skill set but also allow you to develop contacts within the community and even create opportunities for freelance work.
It takes some time to build up the knowledge and skills necessary to become an active contributor (especially because documentation often requires a different skill set than programming), but it’s worth the investment.
Challenges of Contributing
Technical writers can face several challenges when they start contributing to open-source projects. One of the most common is not being sure how best to contribute, especially if you don't know anything about the project yet.
You might also be unsure about where your work should go or what is expected from contributors. There are a couple of ways around this problem: you can read the project's README file and/or documentation to see if they have contribution guidelines. You can also get in touch with the team behind the project and ask for help.
How to Contribute to Open-Source Projects
First, you'll want to find a project on GitHub you want to contribute to. You can read this tutorial about how to search GitHub and find projects.
Next, you'll want to open the README and make sure you understand the given instructions.
Then, fork the repo by clicking on Fork located at the top right corner of your screen.
Clone the forked repo in your local computer using the following command:
git clone <LINK TO THE REPO>You'll see the repo link when you click on the code dropdown.
Once you've cloned it, open up the directory containing your new fork and start adding your contribution.
When done push your changes on GitHub by using the following instructions:
git status //displays which modifications have been staged.
git add . // adds changes to the cloned repo
git commit -m "changes" //performs a commit to the cloned repo
git branch -M changes //creates a new branch
git push -u origin changes //pushes the changesYou will be prompted by GitHub to create a pull request after pushing your changes to the cloned repo. Go ahead and create the pull request and wait for the maintainers to merge your cloned repo to the main repo.
Make sure to incorporate upstream modifications into your local repository if you forked the project a while ago.
If you encounter a large file, install git-lfs if it is not already installed with the following command:brew install git-lfs
By downloading the appropriate versions of huge files slowly, the Git LFS (Large File Storage) extension, created by Atlassian, GitHub, and a few other open-source contributors, lessens the impact of large files in your repository
You can also use the following documentation to install git-lfs.
Best practices when contributing to open-source
- Identify an area where you could be of assistance and find the relevant project on GitHub.
- Read the documentation for any projects or programs that may be similar to the one you're interested in. This will give you a better understanding of what is involved in contributing and what other people have contributed.
- Search for issues labeled good first issue and read through them – these are typically fairly easy to solve.
- Get your code ready by following the contribution guidelines of the project.
- Write up a pull request with your solution and explain why it solves the problem at hand. Include links to related resources like tutorials if necessary.
- Submit your pull request for review. The team will discuss whether it should be accepted into the repository and update you about their decision.
- If they decide not to accept your pull request ask them how you might go about addressing their concerns so that they'll reconsider acceptance at a later date.
- If they do accept your pull request then thank them!
- Continue searching for new problems to solve and share your progress along the way!
What Types of Contributions Can I Make?
You can contribute to these projects in many ways, including submitting pull requests for bug fixes or feature additions, writing documentation about how to use the software, improving the current documentation, translating the text into another language, and fixing typos.
You should get involved by picking a project you're interested in and reading through its documentation before diving right in.
Writing for an open-source project is a great way to establish yourself as an expert in your field and position yourself for future freelance opportunities.
One thing that technical writers should always keep in mind when writing for open-source projects is that their audience is primarily developers. This means that they need more technical details than what you would find in other types of writing.
Where Can I Find Open Source Projects?
There are a variety of places you can find open-source projects. GitHub is the most popular place for open-source projects, but there are also repositories on BitBucket, Gitlab and other sites.
If you have an idea for an open-source project that doesn't exist yet, start by putting together your plan in a README file. If you're not sure how to get started with contributing to an existing project, check out its documentation or read through some pull requests before submitting one of your own.
Sample Projects
- The HTML5 Boilerplate project is a popular open-source project for web developers that provides HTML, CSS, and Javascript code for building a website or web application.
- The Bootstrap framework, also an open-source project, is a collection of tools to help developers quickly create responsive websites.
- Jekyll is a static site generator written in Ruby, designed for personal blogs.
- React.js documentation - React.js documentation provides official information on how to use react.js
- GitHub pages - They contain everything you need to know about GitHub.
- Galaxy project (training material) -A collection of training materials about the Galaxy project which is a web-based open platform for data-intensive computational research that extends beyond the biological sciences.
- CNCF (Cloud Native Computing Foundation) -CNCF is open-source cloud-native computing that hosts projects such as Kubernetes and Prometheus to make cloud-native ubiquitous and sustainable.
You can also check out Google Season of Docs which provides assistance to open-source projects in improving their documentation and allows skilled technical writers to acquire experience in open-source.
There are many different ways you can contribute, which means there is something out there for everyone.
Conclusion
Contributing to open source is a great way for technical writers and other content creators to share their knowledge with the world.
There are many different ways you can contribute, which means there is something out there for everyone.