The Technical Writers Guide to Contributing to Open Source Projects
The documentation of an open source project provides an avenue for users to understand the project and contribute to it. Surveys have even shown that good documentation serves as a sign of an open source project's healthiness.
Yet, few open-source projects can claim they are well documented, and many others struggle to keep their documentation up to date.
As important as open source projects' documentation may seem, most technical writers shy away from contributing to open source projects because they don't know how to or they are influenced by the stereotype that only software engineers can contribute to open source.
This article aims to provide an introductory guide for technical writers who want to contribute to open source projects. It will cover how to get started, best practices, benefits, and insightful resources for further learning.
Table of Contents
- What is an open source project?
- Why are technical writers important in open source?
- How can technical writers contribute to open source projects?
- Some notable best practices.
- Benefits of contributing to open source projects as a technical writer.
- Resources & further reading.
What is an open source project?
An open source project is a project whose source code and documentation are made available for use, modification, or enhancement by anyone in the world.
Did you notice that I said "anyone in the world" and not "only software engineers"? That's because anybody can contribute to an open source project.
Why are technical writers important in open source?
Based on a survey carried out in 2017 by GitHub, the major problem encountered in open source projects is incomplete or confusing documentation.
This means that people decide not to use an open source project or contribute to it because of the documentation. - So, if technical writers come onboard and become active open source contributors, this problem will be solved, and more people will contribute to or use more open source projects.
Hence, the documentation of an open source project is arguably as necessary as the software. So, technical writers are as important as software developers in the open source ecosystem because humans can't use what they don't understand.
How can technical writers contribute to open source projects?
This section covers a guide for technical writers who want to contribute to open source projects.
Find a project you can contribute to
As explained at the beginning of this article, the documentation of so many open source projects is incomplete or confusing, so there are many projects that you can improve. The first thing you need to do is identify the project you can contribute to. If you are interested in Pytorch, you should look out for open source projects using PyTorch since you already have a basic understanding of the tools used. Here's a list of open source projects with documentation opportunities.
Identify an issue to solve
After identifying the open source project, the next thing you need to do is identify an issue to solve. Most open source projects already have available problems relating to their documentation, while others don't.
If you happen to work with an open source project that has raised documentation issues, notify the maintainers of your interest in the project, and start working on it.
If you don't see available documentation issues, then try using the project and identify things that should be documented but haven't been. Then write it and submit a pull request.
Send a pull request
Before submitting the pull request, try to understand the open source project's review process and how they expect to submit pull requests. Ensure you follow the style guide when submitting your pull request.
Some notable best practices
- Follow a style guide (if it exists).
- The page title should reflect the content of the page.
- Always define what the page is about in the first paragraph.
- Consider your audience when creating content.
- Avoid duplicating content.
Benefits of contributing to open source projects as a technical writer
Even though contributing to open source organizations is done for free, there are so many benefits from it. Here are some of the benefits of contributing to an open source project as a technical writer.
Your writing skill will improve
Due to open source projects' nature, contributions are always reviewed by at least one maintainer before it is merged. This means you automatically get access to more reviews and feedback that you naturally didn't have access to.
By implementing this feedback on your pull request and working with maintainers and contributors from different parts of the world, your writing tends to improve over time.
You expand your network
Besides improving as a technical writer, you also get an opportunity to work with people doing extraordinary things in the Open source space. For instance, if you work with an organization like VideoLAN organization, you automatically build relationships with other developers, writers, and top maintainers of the project. Remember having a good network of people in your space is very important for your career.
You can get recommendations and referrals
When applying for any job, having a good recommendation letter often helps to strengthen your application. Working closely with a maintainer of any open source project presents an opportunity to secure a rich source of recommendations and referrals.
You can get accepted into the Season of Docs program
Season of Docs is an annual program organized by Google. Its goal is to bring technical writers and open source organizations together to foster collaboration and improvement of documentation in the Open Source space.
As a technical writer who contributes to open source projects already, your chances of getting accepted into the Season of Docs program is super high already.
You become an open source contributor
This is my favourite benefit because every technical writer contributing to an open source project helps the world debunk the stereotype that open source contributions are only meant for Software developers.
Improving documentation is an impactful way to contribute back to open source, and contributing to an open source project opens you up to many opportunities.
I hope you could learn about contributing to open source projects as a technical writer in this article. If you have any questions, you can leave it in the comments section below, and I'll be happy to answer every single one.
Like this article? Follow me on Twitter @didicodes.
Resources & Further Reading
I curated a list of useful resources to help you learn more about contributing to open source projects as a technical writer.
- "How technical writers can help open source contributors get started," Sarah Maddox.
- "Documentation as a gateway to open source," James Turnbull.
- "Open Source contributions: A catalyst for growth," Edidiong Asikpo.
- "Introduction to open source Documentation," Developer Circles from Facebook.
I do have some questions:
What skills should someone possess to become a technical writer, efficiently contribute to Open Source or even land a job as a tech writer?
Is it possible to contribute to the developer docs of a project when you can't code in the languages the software was written. (Most times dev docs have quite an amount of coding explanations and examples)
#1. To become a technical writer, you need to have the following skills: Technical skill, Audience perception, writing skill, ability to carry out research, and a unique voice. I explained all these points in the article below.
#2. Yes, it is absolutely possible. You can start from rearranging the structure of the developer documentation to make it more user friendly or correcting typos to eventually understanding more about the language used to build the product. Also, you can reach out to the engineers in the team to help you explain some important concepts as well.
What a great post, Edidiong. I am a senior tech writer based in Auckland, New Zealand just about to start contributing to my first open source project! Thank you for building my confidence even more!