A Technical Writer’s Guide to Contributing to Open Source

Open-source software has become an essential part of the modern technology landscape, powering everything from operating systems to web applications. Behind every successful open-source project, there’s a dedicated team of contributors who help make it happen.

Table of Contents

Introduction

As a technical writer, you have a unique set of skills that can be valuable in contributing to open source. Your ability to clearly and concisely document software features, APIs, and processes can help make open-source projects more accessible to users, developers, and contributors. The role of technical writers in open-source projects is vital in creating documentation that helps users understand how to use the software.

I can attest to this because as an Outreachy intern with Wikimedia, my project was to work on documentation improvements to the ~20 top 100 most viewed MediaWiki Action API pages on-wiki, and contributing to this improved my documentation skills as well as helping others to understand the software better.

In this article, I’ll outline reasons why contributing to open source as a technical writer is valuable, how to get started, and best practices for making meaningful contributions.

Benefits of contributing to open source as a technical writer

There are many reasons why contributing to open source as a technical writer is valuable.

Building a portfolio: Contributing to open-source projects can provide you with a portfolio of work that showcases your technical writing skills. This can be especially helpful if you are looking to land a job in the tech industry or want to establish yourself as a subject matter expert in a particular field.
Improving your skills: Working on open-source projects can help you improve your technical writing skills. By contributing to open-source projects, you can gain experience with new tools and technologies and demonstrate your ability to work collaboratively with others.
Making connections: By contributing to open-source projects, you’ll have the opportunity to connect with other technical writers, developers, and members of the open-source community. These connections can lead to new job opportunities, collaborations on future projects, and a support network of peers.
Giving back: Contributing to open-source projects is a way to give back to the community. Open-source software is built on the principle of collaboration and mutual support, and by contributing to open-source projects, you can help make software better for everyone. By documenting your work and making it accessible to others, you can help ensure that open-source projects are accessible to a wider audience.
Learning new tools and processes: Contributing to open-source projects often requires using tools and processes different from those you might be used to. By understanding these new tools and methods, you can expand your skillset and become a more versatile technical writer.

Technical writers’ contributions to open-source projects

As a technical writer, you can contribute to open source through writing;

Documentation: Technical writers can improve the project’s documentation by creating, updating, or reviewing existing documentation. This can include user guides, developer guides, API references, and other technical documentation.
Tutorials and How-to Guides: Technical writers can create tutorials and how-to guides to help users understand how to use the project. These can be in the form of blog posts.

Getting started with open source as a technical writer

If you are a technical writer interested in contributing to open source, these are the steps you can take to get started:

Step 1: Find a project that interests you

The first step to getting started with contributing to open source as a technical writer is to find a project that interests you. There are many open-source projects out there, so take some time to explore and find one that aligns with your interests and skills.

Here are a few resources for finding open-source projects:

You can use the Explore and Search features to find projects that you can contribute to.

Step 2: Understand the project

Once you’ve identified a project, start by reading through the project’s documentation to get a sense of what’s already been written. This will help you understand the project’s goals, features, and user base. Look for areas where you can contribute to the documentation, such as adding new sections, updating existing content, or translating the documentation into different languages. Before contributing, you should review the project’s code of conduct or community guidelines.

Step 3: Follow the Project’s Guidelines

Every open-source project has its guidelines for contribution. Take the time to read and understand the project’s guidelines, including its code of conduct, contribution guidelines, and documentation standards. Adhering to these guidelines will ensure that your contributions are welcomed and accepted by the project’s maintainers.

Step 4: Contribute to the Documentation

One of the most important ways that technical writers can contribute to open source is by improving documentation. Documentation is essential for users and contributors to understand how to use and contribute to a project. Look for areas of the documentation that need improvement or expansion and contribute by writing new content, updating existing content, or reviewing and editing the document.

Step 5: Submit a Pull Request

Once you have made your contribution, submit a pull request for review. A pull request is a request for the project’s maintainers to review and merge your changes into the project’s codebase. Be prepared to receive feedback and make changes to your contribution as needed. Remember to be patient and respectful in your interactions with the project’s maintainers and other contributors.

Here’s a guide on how to submit a pull request.

Standards for contributing to open source as a technical writer

When contributing to open source as a technical writer, here are five best practices to keep in mind:

Understand the project’s goals: Before you start writing documentation, make sure you understand the project’s goals, features, and user base. This will help you create documentation that is useful and relevant to the project’s users.
Follow established conventions: Many open-source projects have established conventions for documentation, such as formatting, style, and tone. Make sure you follow these conventions to ensure consistency across the documentation.
Use plain language: Avoid using technical jargon and complex language in your documentation. Use plain language to make your documentation accessible to a wide range of users.
Write for your audience: When writing documentation, keep your audience in mind. Tailor your documentation to the needs and skill levels of the project’s users. Here’s an article on audience analysis to guide you.
Collaborate with others: Open source projects rely on collaboration, so be open to feedback and collaboration with other contributors. Use the project’s communication channels to ask questions, share ideas, and collaborate with others.

Conclusion

Contributing to open source as a technical writer is a great way to gain experience, build your portfolio, and give back to the community. Whether you’re creating documentation, reviewing code, or participating in the project’s community, there are many ways to make a meaningful contribution.

By following best practices and collaborating with other contributors, you can make a positive impact on the project and the wider open-source community. So don’t hesitate to get started and begin your journey as an open-source contributor today.

Follow me on Hashnode and Twitter for more articles on open source and technical writing.