Introduction

If you're a technical writer wondering how to contribute to open source by documenting, or if you're simply curious about open source and its connection to your role, then this guide is for you. I'll walk you through the basics of contributing as a technical writer.

What is Technical Writing?

Technical writing is the art, or the ability, to explain technical jargon or concepts in a written form. It is also a type of writing that focuses on explaining technical terms, ideas, jargon, and concepts in a simplified manner.

What is Open Source?

Open source, as the name suggests, is a concept or term used for software with source code that is free to use, modify, inspect, and more. Not only is the source code open, but its documentation is also open, making it accessible to a wide range of contributors beyond just programmers. The software is available for anyone to use and modify, and it's publicly accessible.

Various Ways to Contribute to Open Source as a Technical Writer

You might have thought before now that open-source is meant entirely for developers, but that’s not true. Here’s how to contribute to open-source without writing codes:

Creating documentation for a product or software.
Creating user guides and manuals.
Providing in-depth tutorials for a project.
Improving documentation by fixing a typo, revising it, or expanding it to keep it up to date.
Providing feedback from user experience tests.
Translating documentation into other languages, making it accessible to speakers of different languages.

Why Technical Writing is Needed in Open Source

One thing I learned from an experienced technical writer and software developer is that developers often find it challenging to write documentation, leading to incomplete or confusing instructions. Without documentation, especially for the general public or non-technical users, understanding and using a product or software can be a daunting task.

Here are some reasons why technical writing is needed in open-source:

To end the era of incomplete, confusing, and jargon-filled documentation.
To create documentation that is clear and concise.
Translating code into documentation makes it easier for both developers and non-developers to understand how software functions.
Providing easy-to-follow, step-by-step guides for using a software or product.
Developing clear documentation for new team members to follow through.
To encourage people to contribute to open-source through user-friendly documentation.

Getting Started with Open Source Contributions as a Technical Writer

Find a project you’re interested in and can contribute to.
Go through the project or its Readme file and identify an issue that needs to be solved. You can do this by checking the ‘docs’ label under the ‘issues’ tab.
Inform the maintainers of the issue you found and express your interest in solving it.
Submit a pull request. Before doing this, review the style guide and contribution guidelines on how to submit a pull request and make sure to follow them.
Start with small tasks.
Join the project’s community.

Important things You need to know before Contributing to Open-Source

Git and GitHub: According to Simplilearn, Git is a free, high-quality distributed version control system suitable for tracking modifications in source code in software development. It was originally created as an open-source system for coordinating tasks among programmers, but today it is widely used to track changes in any set of files, while GitHub is a web-based Git repository. This hosting service has cloud-based storage. GitHub offers all distributed version control and source code management functionality of Git while adding its features.

Many software development teams and open-source projects use Git and GitHub to manage their source code, track changes, and collaborate effectively.

Contributing to open-source is not limited to Git and GitHub. There are other alternatives like Gitlab and Bitbucket with similar functionality.
Basic Git commands: Actions like cloning a repo, committing, pushing, pulling, merging, and forking a repo, will be frequently used by you. To learn all the Git commands, check out this article from Atlassian on "Git commands."
Markdown: This is a lightweight language that allows you to format text using a simple, human-readable syntax. It was designed to be easy to write and read, and it’s commonly used for creating documents, web content, and documentation. It is easy to convert to other languages.

Some Best Practices for Contributing

When documenting, follow the style guides and coding standards of the documentation.
Ensure your commit message is well explained.
Join the community.
Ask for help or clarification when needed.
Test your changes before submitting a pull request(PR).
Begin with small, manageable tasks.

Tools and Technologies Needed to Get Started

Markdown.
Writing tools: Google Docs, Notion.
Editing tools: Grammarly, Quill bot.
Publishing tools: Hasnode, medium.
Google for research.

Benefits of Contributing to Open Source as a Technical Writer

Builds your portfolio.
Improves your writing skills.
Gain experience/value.
Expand your network.
Learn new tools and technologies.
Learn to collaborate or work with people, and developers.

Where to Find Open-Source Projects

There are various platforms to find open-source projects, but the commonly used one is GitHub. You can search for projects through its search feature based on your interest e.g. python. Check for any issue under the ‘issues’ tab with the label ‘doc,’ or you can simply go through the project’s Readme.

Helpful Resources

Conclusion

This guide covers everything you need to know about contributing to open source as a technical writer, from the definition of open source and technical writing to the necessary steps to take to get started with contributing. With the knowledge provided here, you can begin your journey of contributing to open source as a technical writer.

When clear and concise documentation is available, people and developers would be more willing to contribute to open source in various ways. Start contributing to open source today.

Technical Writing in Open-Source: A Guide to Contributing

Table of contents