Writing For Devs: A Technical Writer's Guide To Open Source

This post was first shared on Zaycodes as a part of the the Zaycodes WriteTech Bootcamp.

As a technical writer, what do you think of when you hear the phrase 'contributing to open-source'?

If you're a beginner, you'd most likely be thinking of the world of open-source as a vast place where only developers can contribute to.

Or you might have even heard that contributing to open-source is a good way to build expertise as a technical writer but you don't know how how get started.

Most technical writers are in a similar category - shying away from making contributions to open-source projects either because they don't know how, or because they think only developers can contribute to open-source. This article aims to address both of those issues, while also providing an introductory guide that'll make it easy for any technical writer that wants to get started with the world of open-source projects.

It will serve as a roadmap to helping you understand how you, as a technical writer; can become an effective collaborator in the world of open-source: covering open-source benefits and best practices, things every technical writer can contribute, places to find projects, and practical ways to get started on an open-source project.

Let's dive in!

What is Open-Source?

The term 'open-source' refers to any project or software whose source code and documentation has been made available to all. This means anyone can view, use, and edit or modify it. Open-source advocates believe in the principles of transparency, collaboration, shared innovation, and community-driven development. Open-source contributions - from enthusiasts, professionals, and even corporations - are essential to a lot of software projects worldwide.

Open-source has a rich history that dates back to the early days of computing - a time when software was shared freely amongst its users. While the term "open-source" was coined in 1998 by Christine Peterson, the concept powering it has been around for much longer - as early as the 1960s. The GNU General Public License, the Free Software Foundation, Linux, as well as programming languages like Ruby and Python, are all products of the open-source movement. Open-source encourages collaboration and transparency in software development, accepting contributions from a community of developers and users.

A Technical Writer’s Place In Open-Source

In the building of any software, the documentation is just as important as the codebase itself. Having a product that no one will use because they don’t understand how to use it, is the same as not having a project at all.

Technical writers solve that problem as an important part of the open-source ecosystem, creating guides, articles, and other types of documentation that ensures potential users understand and are comfortable with the product or language. Technical writers make a variety of contributions to open-source, which include but are not limited to:

FAQs (Frequently Asked Questions), which are usually inserted at the end of introductory guides to a product or program.
User guides, mostly for user-oriented products/software, they are introductory guides to basic features of the product.
Tutorials and how-to-guides for different features.
Reference guides.
Whitepapers.
Blog posts and articles.
Knowledge bases (KB).
API Documentation.
Editorial contributions such as proofreading/checking for errors.
Translations in other languages.

As you can see, technical writers have a lot to contribute.

Exploring The Benefits

So now that you know that you can contribute to open-source projects as a technical writer, why should you even try? What benefits can you gain by contributing to open-source?

Building a Portfolio:

Making contributions to open-source projects allows you to easily build a portfolio - which serves as proof of your skills and experiences as a technical writer. This is important if you're actively pursuing opportunities in the tech industry, or seeking to establish yourself as an authority in a particular field.
Working With New Technologies:

As a technical writer contributing to various open-source projects, you will have to learn new skills (such as making a pull request or cloning a Git repository) and work with different tools, technologies and techniques. Some of which will be different than the ones you might be used to. Learning to work with these will effectively broaden your skill set, give you opportunities to work with diverse teams/departments, and open you up to even more job opportunities.
Expanding Your Network:

Participating in open-source projects introduces you to a diverse range of fellow technical writers, developers, maintainers, and community members. You'll get to meet different professionals that will be a part of your support network, and these connections can help you with further collaborations on future projects, strong recommendations and referrals from maintainers, and even job opportunities.
Improved Writing Skills (via Feedback):

In contributing to open- source, you expose your work to a global audience. And because open-source contributions are usually reviewed by experts on an international scale before they are accepted, your work will almost always get reviews and feedback from different maintainers - for free! You will quickly learn and refine your skills as you receive feedback and other kinds of reviews, and your work will naturally improve.
Contributing to Something Significant:

Contributing to open-source is a way of giving back to the community by contributing to something significant. As open-source is based on the principles of transparency, cooperation, and support, you play a very important part in making sure software remains accessible to a wider audience, making the project better for everyone . You are now a part of its story.
Access to Special Programs:

As a technical writer, having a previous history of open-source contributions makes it easy for you to be accepted in other programs like Outreachy and Google Season of Docs, which are widely regarded within the technical community and are designed to further develop your technical writing skills and broaden your career prospects.

Tools of the Trade

As a technical writer wanting to contribute to open-source, you should have - or know - the following:

Basic technical writing skills. In addition to my technical writing guide for beginners, Zaycodes conducts routine technical mentorship programs that can help you master basic technical skills.
Git and GitHub. Git and GitHub (or any other Git-based variations like Gitlab or BitBucket) are Version Control Systems (VCS) regularly used in open-source for collaboration. You can find an easy-to-understand introductory guide to Git/GitHub here.
Using open-source community communication tools like Discord and Slack.
Documentation formats like Markdown or restructured text, or which are easy to learn.
Sometimes, a basic knowledge of the programming languages used for the project is needed.
Communication skills are important as you'll be working with people from different backgrounds, countries, and age groups. Knowing how to communicate is an essential skill.
The Docs-as-code approach to documentation, which simply refers to the philosophy of treating your documentation like code; managing it using the same systems, processes and tools (like Git and GitHub) as you would use with code.
Finally, an insatiable desire to learn new things. Sometimes, you may not have all the skills to work on a documentation task. However, technical writers must always be able to learn on the job, embracing new technologies in order to complete their task.

Finding Open-Source Projects

Now that you know why contributing to open-source is important - and even beneficial, where can you find good open-source projects to contribute to; especially if you are a beginner? Well, here's a list of good places to get started:

GitHub. Many open-source programs share their code, documentation, as well as contribution criteria on GitHub. You can go to the Explore tab and search for 'good first issue' or 'good contribution' and 'docs' or 'documentation' in order to see examples of good projects you can contribute to as a beginner technical writer.
Social media. Social media, especially Twitter (X) can be a good source of open-source projects as both individuals and organizations in open-source communities share announcements regarding their open-source projects on the platform. A quick search using the tags: open-source, open-source for beginners, beginner open-source, open-source documentation, will quickly yield results.
Up-For-Grabs.net.
First contributions.
Goodfirstissue.dev.
Code Triage.
opensourcefriday.com.
First Timers Only.
Your First PR.
Mozilla's Knowledge Base.

I found this article by Ashutosh Mishra extremely helpful in identifying places to check out for beginners that want to open-source.

Getting Started with Open-Source

Now you've found a potential project. What should you do next?

Step 0: Read the README.md and CONTRIBUTING.md documentation. Every open-source project has one of those as they detail guidelines for contributing to them.

Step 1: Find a problem to solve. You can do this by searching through the issues tab using filters like 'good first issue', 'docs' or 'documentation'. Most open-source projects have preset tags for documentation-related issues as most of them have already identified problems relating to their documentation.

Others however, have not raised available documentation issues. In that case, it is up to you to check out the project's docs (usually hosted on that same repository), and identify things that you feel are lacking. Once you've done this, note it down as an issue and notify the maintainers of the project.

Step 2: Start work on that part of the project. The normal way to do this is to fork the repository to your own GitHub before cloning it, and then working on the documentation on your local device, according to the contribution guidelines. Here is a simple guide to forking and cloning repositories on GitHub.

Step 3: Submit a pull request. Make a pull request on GitHub (or the variation) with your solution, giving a description on why it solves the issue. Make sure you check out the project's review process if there are special rules for submitting pull requests. Feel free to include links to other sources that explain why you used the approach you used while working on that documentation.

Step 4: Be patient. The maintainers are not bots - they are also human beings like you with normal human lives trying to give their best as volunteers in an open-source project, without being paid. That is hard enough. Be patient, be polite, and be respectful.

Step 5: if your pull request is accepted, you will be updated on their decision. However, if they do not accept your pull request, feel free to ask for feedback on their concerns with your solution. Address those concerns if you can, and if you can't, thank them for the feedback regardless.

Open-Source Tips and Best Practices

Make sure you have a fairly good understanding of the project’s goals, features, and established user base (or potential users).
Always check the README or the CONTRIBUTING files of any project you are interested in. This cannot be overstated, as those files always contain important guidelines on how you can contribute properly to any project.
Once you've picked an issue that you want to work with or solve, always make sure you leave a comment on that issue so that other people can register your interest in it. Remember to also notify the maintainers of your interest in the project, so you can get a formal go-ahead to start working on it.
Note the choice of formatting, naming conventions, tone, and style guide used, and try to adhere to the same. If there's no style guide, follow already existing style guide standards for technical writers while still adhering to other established conventions for the sake of consistency.
Always consider your audience in any form of documentation that you write. The audience of user guides might not be the same as the audience of an API doc.
Make sure you join the community channels, where you can learn valuable insights. Check out their Slack, Discord, or any other links.
Make it a point to always ask for help from other community members when you need it. Trust me, you will. Feedback, knowledge sharing, and collaboration with others are central to open-source development.

Conclusion

Contributing to open-source projects is a great way to put yourself out there as a technical writer, build a reputable portfolio, and share your knowledge with the world.

Your role as a technical writer in open-source is vital. Your words bridge the gap between complex technology and its end-users, making the software truly accessible and usable for all. As a technical writer, your contributions will improve the overall quality of open-source projects, you will become open to more collaborations and opportunities, and you will consistently grow in your skills as you make a positive impact in the open-source community.

Now that you know how open-source works (and how you can play a part), don't hesitate! Become an open-source contributor today.

Technically James

Technically James

Writing for Devs: A Technical Writer's Guide To Open-Source

You're a technical writer. You've heard about open-source. You're confused. Now what?

Table of contents