Have you ever wondered how to contribute to open-source projects as a technical writer, what kind of contributions you can make, and what the benefits are? This article is for you.

Open source contributions have enabled global collaboration in the ever-changing world of software development, fostering faster innovation and the development of more advanced, reliable software projects.

Unfortunately, open-source documentation is frequently poorly written or nonexistent, impeding development and discouraging potential contributors. Few open-source projects can brag about being well documented, and many struggle to keep documentation up-to-date.

Most people believe that open-source contributions are only for software developers. What if I told you that every open-source project requires a Readme.md file and a well-written documentation guide?

This article is an introductory guide for technical writers interested in contributing to open-source projects. It covers getting started, technical writer contributions, skills and tools, best practices, benefits, and valuable resources for further learning.

Understanding open source and the importance of technical writing contributions

Contributing to open source is a rewarding way to learn, teach, and gain experience in various skills. It not only improves your writing skills but also allows you to collaborate with global teams to create high-quality documentation.

To move forward with this discussion, you must first understand the concept of open-source and your role as a technical writer. Understanding the tasks, skill sets, and tools required for contribution is essential.

What is open source?

Open-source, also known as open-source software, is software with source code that anyone can inspect, modify, and improve.

"Source code" is the part of software that most computer users never see; it is the code that computer programmers can change to alter how a piece of software—a "program" or "application"—works.

An open-source project includes both its source code and documentation. It is worth noting that open-source contributions are not limited to software engineers or programmers; designers, technical writers, product managers, and even community managers can participate.

Why are technical writing contributions important?

“Even if you write an amazing program, no one will use it if you don’t explain what it does and how to use it.” -Nate Waddington

The documentation of an open-source project is just as important as the software itself. As a result, technical writers are just as important as software developers in this ecosystem.

Based on a survey carried out in 2017 by the Open Source Survey, the major problem encountered in open source projects is incomplete or confusing documentation.

Sharing information through READMEs, contribution guidelines, and issues is open source projects’ secret sauce: they invite new contributors and make developers 55% more productive, according to the 2021 State of the Octoverse report. Hence, the open-source ecosystem needs more technical writers to contribute to open-source documentation.

Skills and tools required for contributing to open-source

This section covers the skills you need to contribute to open-source projects as a technical writer

Good writing and communication skills

Well, it is called technical “writing,” so you need to know how to write. You have to be able to write clear and concise sentences that help your audience understand the topic you are writing about without confusing them.

When engaging in activities like committing changes, raising issues, submitting pull requests, and writing comments on GitHub, it's important to prioritize clear and concise writing. As an open-source technical writer, you will collaborate with developers and interact with contributors of various backgrounds, ages, and orientations.

If you have doubts about your technical writing skills, you can enhance them by enrolling in a writing course, dedicating time to practice, and reading a variety of technical articles to enrich your vocabulary and writing style.

The technical writing course by Google is a free course I always recommend because it helped me improve my writing.

Programming language knowledge

This is where the term "technical" in technical writing comes into play. You must have technical knowledge to write technical articles. How can you write about something you don't understand or know anything about?

For you to be able to contribute to some open-source projects, you must have a basic understanding of the language used to build the project. Some recommended languages to learn are Python because it’s easy to learn and easy to read, and JavaScript, mostly because it’s everywhere.

Fast learning and research abilities

As a technical writer, you are likely to have to write about topics that are unfamiliar to you. You may be required to grasp complex programming concepts at times quickly. As a result, you must be adept at conducting research when necessary to gain a thorough understanding of a topic and write about it concisely, even with limited time.

Recommended open-source tools

You need to have a basic understanding of version control systems like Git, GitHub, BitBucket, GitLab, etc., for effective collaboration
Chat services such as Slack or Discord for their asynchronous communication
Markdown, XML, Wiki syntax, reStructured texts, and other common source formats used in documentation

How to contribute to open source projects as a technical writer

This section contains a how-to guide for technical writers interested in contributing to open-source projects.

Understand how a project works

Open-source projects vary in their operations. Some allow contributions from anyone, while others require a hierarchical approach. They often provide contribution guidelines, a code of conduct, and governance policies to guide contributors. These documents help you understand the project's structure and expected behaviour.

To become an effective contributor, study the technical aspects through documentation, README files, and past contributions. Engage with the community through communication tools like Slack, Discord, IRC, and newsletters, and build relationships with other contributors.

Because open source projects each have their own distinct coding styles, team cultures, and workflows, it is critical to adapt and learn as you go in this diverse and collaborative environment.

Find projects to contribute to

There are many open-source projects with incomplete or outdated documentation that you can find and contribute to. One way to find projects to contribute to is to look for projects that you already use and see if they are open source and require documentation. Working on things you already use gives you an advantage when contributing because you already know how they work and have experience using them.

Another way is to use the GitHub Explore page to find projects that are accepting contributions or actively want help. GitHub recommends projects based on your activity, but you can also search for projects. Use GitHub's search tool and apply tags like good-first-issue, good-first-bug, first-timers-only, easy, and more to find beginner-friendly contributions. Filter results for open issues in your preferred languages.

For a positive contribution experience, avoid communities that are unwelcoming to beginners. It's best to avoid anyone who makes dismissive or insulting comments after asking legitimate questions. Be wary of repeated unprofessional behaviour within a community. Some open-source projects have had problems with this, so do your homework before contributing.

Choose a problem to solve

Now that you've found a project to which you'd like to contribute, look for issues tagged for beginners with the previously mentioned tags. Start with the simplest and smallest contributions that require the least amount of work and time to build your confidence and credibility before attempting more difficult contributions. Writing documentation and correcting typos is a good place to start.

After deciding on a task that you believe you can complete, do extensive research by delving into documentation, code, and related discussions to gain a thorough understanding of the task. If you run into problems despite your research, don't be afraid to ask for help, clarification, or mentorship from the community.

Once you're comfortable with the task and your approach, write the necessary documentation and submit a PR (pull request) using GitHub's checklist to ensure your contribution meets the project's standards and requirements.

Make a pull request

After making your contributions, it’s time to create a pull request. Try understanding the open-source project's contribution guidelines and how they expect you to submit pull requests. If your submission doesn't receive a response after a while, politely request a review or seek assistance from other contributors.

Make post-review changes as soon as possible to ensure your contribution remains relevant. If your contribution is rejected, seek feedback to find out why. Try to remain active after making your contributions so that when reviewers or maintainers provide feedback or ask questions, you can easily work on updates and stay relevant.

Though open source contributions are free, treat them like any other work and be professional, courteous, and respectful.

Best practices when contributing to open-source

Follow a style guide (if one exists)
Create a pull request with your solution and explain why it solves the problem at hand. If necessary, include links to related resources, such as tutorials
Make your sentences clear, and consider your audience when creating content
Avoid duplicating content

What kind of contributions can a technical writer make to open-source projects?

Technical writers can contribute to open-source projects in a variety of ways, depending on their skills and the needs of the project. You can start by correcting typos and grammatical errors or by developing onboarding materials to assist new contributors in understanding the project and getting started.

Technical writers can also work on the following:

API Documentation
Product Documentation
User guides and manuals
Technical reports
Tutorials
Whitepapers
How-to-guides
FAQs
Blog posts and knowledgebase articles
Release notes, among other forms of documentation

The best part is that you don't always need to have prior experience to work on these documents; you can always learn on the job, practice more, and ask questions.

Benefits of contributing to open source as a technical writer

Many people always ask, "What do I stand to gain if open-source contributions are free and I can't get paid?" Open-source projects have devised ways to reward their contributors, such as swag, gifts, badges, and so on. Aside from that, there are other benefits, such as:

Enhancing your writing abilities

This, I believe, is the most important advantage. When you contribute to open-source projects, you have the chance to explore new ideas and concepts. Keep in mind that before your contributions become part of a project, they undergo a review process by a maintainer. This allows you to receive feedback on your skills and improve them.

Creating a professional portfolio

Contributing to open-source projects allows you to work on various documentation, which you can compile into a portfolio that showcases your technical writing skills.

This can be useful if you want to get a job in technical writing or establish yourself as a subject-matter expert in a specific field.

Growing your network

You will be able to collaborate with a global community of people and form relationships with developers, technical writers, and top maintainers of various projects. All of these people can attest to your writing abilities, which may lead to new job opportunities and future project collaborations.

Learning new tools and processes

Contributing to open-source projects may require the use of new tools and processes. Adopting new tools and processes can help you broaden your skillset and become a more adaptable technical writer.

Conclusion

Technical writers can use open source to share their knowledge with the rest of the world. Contributing to open source as a technical writer is an excellent way to stretch yourself and gain work experience.

In this article, I've covered essential insights into open source, how technical writers can contribute, and the path to becoming a proficient technical writer.

I hope you found this article helpful, and if you have any questions, please ask, and I'll do my best to answer them.

Resources and Further Reading

What is Open Source?

How to Contribute to Open Source

Contributing to Open Source Documentation as a Technical Writer

Kickstarting Your Tech Career with Open Source

10 skills to land your open source dream job

Contributing to Open Source as a Technical Writer

Table of contents