Contributing to Open-Source as a Technical Writer
Explore opportunities for Technical Writers in OpenSource
Table of contents
Open-Source projects require as many content contributors as they do to code. Technical Writers break down complex concepts for users to understand, adopt and use software technologies.
While this is true, many technical writers don't know how to effectively contribute to open-source projects as the developers who contribute code. One would wonder where to start as the code bases on GitHub and GitLab can be overwhelming for a technical writer with no coding background.
In this article, you will learn how to get involved in open-source projects. We will break it down by discussing the following concepts:
- Benefits of contributing to open-source projects.
- How to find open-source projects
- How to contribute to open-source projects
For anyone not familiar with the term open-source,
Open-source refers to something people can modify and share because its design is publicly accessible. Open-source projects, products, or initiatives embrace and celebrate principles of open exchange, collaborative participation, rapid prototyping, transparency, meritocracy, and community-oriented development.~Opensource.com
Other terms you will see in this document are:
- Maintainers: Are Contributors who have the ability to modify (“commit”) source code, documentation, or other technical artifacts in a project’s repository (“Committers”); They are also referred to as CODEOWNERS on GitHub
- Contributors: Include anyone in the community that contributes code, documentation, pull request reviews, or other technical artifacts to the Project.
Benefits of Contributing to Open-Source Projects.
The rewards you will realize contributing to open-source as a technical writer are endless. They include:
- Advance your Git skills. Git commands like fork, rebase, upstream, and opening issues are not widely used in development, but they are frequently used in open-source.
- Improve your tech skills by studying other people's codes
- Practise and learn valuable skills from reputable projects that you can apply to your own projects.
- Add skills and reputation from worldwide projects to your resume.
Next, let's find out where to find and contribute to the best projects.
Where to Find Open-Source Projects
Find great open-source projects in the following websites:
- GitHubsearch: Find open-source projects on GitHub
- First Timers Only
- Open-Source Friday
- Up for Grabs
- Twitter: Search for projects on Twitter using the #opensource hashtag
- Google Season of Docs: Has a lot of open-source projects that professional technical writers can contribute to.
There are hundreds if not thousands of open-source projects on the internet. How do we identify the best ones? Look out for the following features in any open-source project you wish to contribute to:
- Is the project active on GitHub or any other remote repository? Check when the last commit or pull request(PR) was made. If it is more than 3 months, don't bother.
- Does it have a license? Should have an MIT license.
- Does it have contributors' guidelines? Should be a file on the root folder of the main repository.
- Does it have an active community on social media e.g on Slack, Discord, or Twitter where you can communicate with other contributors?
- Are the maintainers active? Check how long they take to respond to pull requests.
How to Contribute to Open-Source Projects
In order to effectively contribute to open-source projects, you need to have some technical skills. Having technical skills such as Issue Tracking, Version Control (Git), and knowledge of Plaintext Markdown Languages(Markdown), will make it easier to integrate into development team workflows. This approach is known as Docs as code.
Docs as code approach means following the same workflows as development teams and being integrated into the product team. It fosters a culture where writers and developers both feel ownership of documentation, and work together to make it as good as possible. ~writethedocs.org
Now that we have the necessary skills in place, let's go ahead and contribute.
Getting started
1. Pick a Project
Identify a good project to contribute to. You can use our suggestions in the idratherbewriting.
2. Get the contributors' guide
Every good open-source project has a contributors guide. Look for the contributors' guide in the main repository of the project. This document contains simple instructions on how to contribute to the project. It is a guide on how to fork, work on the issue and merge to the upstream repo(repository) to allow for review by maintainers.
These instructions are especially useful to contributors in understanding the workflow and minimizing conflict/clashing with the main project repository. If you don't adhere to these contributors' guidelines your pull request will be closed! Which is highly embarrassing!
Here is an example of a good contributors guide from AsyncAPI.
3. Pick an issue
An issue can be anything you want to contribute to. This can be a request you identified in the issues section on the project remote repository, a typo, or documentation such as the README.md that you wish to add to the project.
Source: issues section on github
It is advisable to first inquire, or discuss the issue with the maintainers before you start working on it. This is because it could be a stale issue or someone else could be working on it.
4. Work on the issue
Once the issue you picked has been approved, go ahead and set up a forked repository by forking and cloning the repository to your local machine. You can then open it on your preferred text editor and get to work. Here you will need to know markdown syntax. You will have something like this:
5. Submit your work for review.
When done, follow the contributors' guide workflow to avail your work for review. You have to connect your local repository to the project's upstream repository using a new branch (all these processes should be clearly documented in the contributors' guide). Next, make a PR (pull request). A PR alerts the maintainers to review your branch and suggest changes before merging. This diagram illustrates a similar process.
source : gitbook.io
6. Reviews and Merge
After submitting your PR, the maintainers will review and suggest changes if need be. You can work on those changes right there on the remote repository by accepting suggested changes (Github has a feature for this) or manually adding new ones. It is at this stage that you can seek feedback and clarification about your work.
When done making your changes, you can make new commits. This notifies the maintainers to review your work again. If all is well, your PR will be quickly merged.
Congratulations! you have just contributed to your first open-source project.
Conclusion
Your first contribution will be intimidating no doubt, but once you learn the workflow, it is easy and fun. I have learned a lot about technical writing since my open-source contribution. I know you will too. Contributing to open source projects allows you to showcase your talents while also learning new skills and technologies. Go on and get started today!
References
To Join our Writing Community, Make sure you follow us and subscribe to these platforms: Slack, Twitter, Telegram, YouTube and Hashnode.