How to get started with contributing to Open Source Documentation as a Technical Writer
October is almost upon us, which means *drumroll* Hacktoberfest! Hacktoberfest is a great time to get started contributing to Open Source as a newbie. It's the time when the maintainers and community members are most active. There are also a lot of Good First issues then, and lots of guides on how to easily find projects to contribute to. Additionally, if you make 4 merged contributions, you can get rewards and have a tree planted for you by Tree Nation if you're among the first 50,000 people. How cool is that!
Contributing to Open Source docs as a Technical Writer can be a bit challenging, because this time, it's not just about writing the article, proof-reading, and publishing, you also have to deal with Git, markdown or Restructured text, formatting checks, documentation managers and any other project specific requirement. This can be quite discouraging, I know. If you'd told me that by this time last year that by now I'd be a top contributor in some Open Source docs, I wouldn't have believed. But here I am now, writing a guide on how to get started with contributing. Trust me, it's not as hard as it seems. You totally got this!
In this guide, we'll talk about things to keep in mind before deciding to contribute to documentation as a Technical Writer, how to select a project to contribute to, what steps to take before you contribute, and tips on how to make a good contribution.
Prerequisites
This guide assumes you're a Technical Writer. This is not a Technical Writing guide.
Things to keep in mind before deciding to contribute to Open Source documentation
You will need knowledge of version control: You will need basic knowledge of Git and a Git provider like GitHub or GitLab. This is what will enable you to create and submit Pull/Merge requests.
Development Environment: You'll need to set up a suitable development environment for the documentation project. This will include installing the required tools, packages and dependencies, a code editor, and possibly a documentation generator like Sphinx or Docusaurus. This also means there are machine requirements you'll need to meet to have an efficient development environment.
Alternatively, you could use a cloud-based integrated development environment (IDE) like Gitpod or Codespaces to set up your development environment.
Documentation Procedures: It's not just the writing part that's involved here. Aside from setting up the development environment and writing, there are other steps involved such as building, passing formatting tests, and deploying the documentation. But don't worry, all projects usually contain clear instructions on how to handle this in their ReadMe file or Contributing guide.
Things to consider before choosing a project to contribute to.
So you've decided that you want to proceed with this, great! The next step is to choose a project to contribute to. Here are a few things to consider before selecting the project:
Knowledge and Expertise on the project: Documentation covers guides on how to do stuff with the project, best practices, the project's features, frequently asked questions (FAQs), references, and lots more. To make a good contribution, you should have made use of the software, or have enough knowledge of how it works, and what features it has.
For a complete beginner to start contributing to a software's documentation, it is best to choose a project based on your niche, especially a tool you've worked with. The reason is that there's often stuff missing from the documentation or something that could be added to make it better, and it's easier to spot them when you've actually used the tool. Generally, it's also easier to come up with what to write on a tool you've worked with.
For example, say you're a developer and when you were installing VScode on your new Linux machine, you went to their docs to look for instructions and you didn't see anything on how to install VScode on Linux, and somehow you later figured out how to do it on your own. Afterwards, you could open an issue in the documentation repository, and submit a pull request on how to do this.
Frequency of Updates: The point of contributing is so it gets accepted and merged. Ensure that the project you're contributing to has active maintainers who are regularly reviewing issues and PRs, and updating the project. Otherwise, your PR will stay there for a while and might never get merged. You can do this by checking the PRs tab to see how recent and how often contributions have been merged.
Active Community: It is easier to make contributions if the project has an active community to provide helpful answers or resources when you get stuck. As someone who is just beginning, you'll probably have a lot of questions along the way. Asking the maintainers is a good way to get help, but they may not always respond promptly. So it helps if there is an active community channel where you can get support from other community members.
Tooling and Tech Stack: Ensure that you're familiar and comfortable working with the tools and technologies used for the documentation, or at least willing to learn them.
Clear Contribution Guide: It is easier to contribute to a project with clear guidelines on how to contribute. From building the project locally to the style guide and formatting, to how to submit the changes you've made for review, there should be a step-by-step process listed in the Contribution guide to direct you in making your contributions. Here's an example of a clear contribution guide:
License: Check the project's repository for the license that says that the project you want to select is Open source. This is just to ensure you're contributing to an Open source project and not someone's project that they made public. Common Open Source licenses include MIT and Apache.
Things to do before getting started on your contribution
So you've gotten past all the steps to take and you've chosen a project you can contribute to. Here are the next steps to take to get to the writing part:
Read the ReadMe and Contributing guide: Even if you know enough about the project, you should never skip reading this. The ReadMe usually contains important things to note about the project.
The contribution guide is the next important thing to look at. As the name implies, this is what directs you on the steps to take throughout the contributing process such as forking the project, creating a new branch, building, deploying, how to make your PR and so on. It could also include things not to do.
Additionally, these files might change from time to time, so it is also good practice to go through them regularly.
Visit the issues tab: The issues tab is where you can look for issues to resolve. Issues usually have tags so if you want to start with something minor, you can search for issues with the 'Good First Issue' tag. Or if you want to contribute something technical, you could search for the "Enhancement" tag. Open the issue you want to work on and ask to be assigned.
However, if you have a contribution in mind that is not listed as an issue, you can create an issue and state that you want to make a PR for it too, so it can be assigned to you. But before you do this, ensure that the issue you want to create does not have a pending PR to resolve it. This is quite important because sometimes, the contribution you might want to make might be something the maintainers have decided that the repo does not need. Imagine spending hours writing a tutorial and making a PR straight after, and your PR gets closed with a response from the maintainer saying they've previously had a discussion on your tutorial and decided not to include it because of security concerns, then adds a link to the discussion. You could've spent this time working on another contribution. However, in the case of typo fixes or punctuation issues, there is no need to create an issue, just make the appropriate changes and provide a good description in your PR.
When creating an issue, ensure it clearly states the problem you want to solve or the improvement you want to make with context, and the solution you intend to implement. It is advisable to wait for feedback from the maintainers on your issue in case they have additional suggestions or insights.
Tips on how to make a contribution
Ah, the writing part. The first documentation contributions I made, I made them directly from GitHub. The project was refusing to build on my machine so I decided to just use GitHub's interface. At some point, I had to figure out a way to build the project because I really couldn't continue like that. Here are some things to keep in mind while making your contribution:
Line breaks: Shorter lines are easier to read. It's easier to review your contribution and highlight areas for changes when everything isn't jumbled up into one line. Here is a guide on semantic line breaks.
One contribution per branch and PR: You probably want the maintainer to review your contributions quickly, but packing all of them into one PR will not help. It'll just make it more stressful. Maintainers review contributions more efficiently when there's a single focus.
For example, if you're correcting formatting issues and you have a tutorial you wrote as well, you should make two separate PRs, one for the formatting fix, and the other for your tutorial. This way your commit message, PR title and description are simple, straight to the point, and the maintainer knows what to expect and look out for.
View your changes. Ensure they appear the way you intend before deploying the changes and making your PR.
Run the formatting tests: Yes, they'll know if you skip them. Documentation needs to follow a pattern because its main purpose is to guide the user. If your contribution uses a different pattern it could confuse the reader. The formatting tests are there to ensure that despite the documentation being written by different contributors, it follows a style guide or similar patterns.
Descriptive PR and commit message: If the contribution guide does not give directions on commit messages or naming your PR, you should endeavor to capture the content of your commit in a short message, and your PR title should explicitly say what the PR contains. For example, a good commit message for a contribution that adds instructions on how to install VScode on Linux could be: "add instructions for installing VSCode on Linux", and it could serve as your PR title as well. This way, the maintainer already knows the content of your PR and what to expect while reviewing.
Pass all required PR checks: There are automated checks for your PR before it gets reviewed. After creating a PR, wait to ensure it passes all required checks. If a required check fails, it means there is probably something wrong in your contribution, like a formatting test failed or something else, and you should review your contribution. Typically, maintainers will not bother with reviewing PRs that do not pass the required checks.
Do not hesitate to ask for help in the community or directly on GitHub or your Git Service provider. If your contribution is taking longer because of other reasons, be sure to communicate that to the maintainer. If you cannot complete your contribution, be sure to inform the maintainer as well, so it can get assigned to someone else.