WriteTech Hub Publication
Navigating Open Source AS A Technical Writer

Navigating Open Source AS A Technical Writer

Mutiat Mustapha's photo
Mutiat Mustapha
·

5 min read

Table of contents

Introduction

This write-up is aimed at providing technical writers with the utmost understanding of the relationship between open source and technical writing and with information on how to get started, best practices in technical writing to consider, some important tools, as well as some technical writing sample projects.

What is open source?

Open source software (OSS) is software that is distributed with its source code, making it usable, modifiable, and distributable for free. It is the code that computer programmers edit to control how a program or application acts. A program can be modified by adding to or fixing broken parts of it by programmers who have access to its source code. OSS usually comes with a license that enables programmers to customize the software to their specific needs and decide how the software is disseminated, and most are peer-produced to encourage open collaboration.

Examples of OSS include GNU/Linux, Mozilla Firefox, VLC media player, Apache web server, etc.

What is technical writing?

Technical writing, simply put, is the writing of technical content in vast fields. The audience for a technical write-up varies with its content. Sometimes, it is aimed at people with specific knowledge (e.g., experts, technicians, etc.); yet, in other cases, a technical writeup assists in communicating complicated issues to end users that need a basic understanding of a topic as opposed to a comprehensive explanation.

Examples of technical writeups are API guides, case studies, whitepapers, websites, datasheets, technical reports, specifications, instructions, and procedures.

The Relationship Between Technical Writing and Open Source

Technical writing is an important part of tech as it contributes to its (tech’s) knowledge pool; it can also be considered an entry port for people newly getting into tech. While technical writing can stand on its own without being tied to open source, open source projects can’t be taken apart from technical writing.

As a technical writer contributing to open source, your task can range from as little as modifying a part of an already-existing technical article to as complex as writing API documentation. All in all, the role of a technical writer contributing to open source (or generally) is not cast in stone but is set under the umbrella of making knowledge and information easily and widely accessible.

Benefits of Contributing to Open Source as a Technical Writer

As a technical writer, there are lots of benefits to be gotten from contributing to open source. Some of them are:

  • Networking: Contributing to open source grants you the platform to meet with others doing the same thing as you, some of whom will be in higher positions you aspire to reach. It helps you build contacts in the community.

  • Improved writing skills: Contributions are vetted by at least one maintainer before being merged. This gives room for reviews and feedback that help develop one’s writing skills over time.

  • Access to recommendations and referrals: Working closely with an open-source project maintainer can help boost your application when applying for any job by giving you the opportunity to get recommendations and referrals.

  • Becoming an open source contributor: Most people believe open source is limited to software developers. When you, as a technical writer, contribute to open source, you help to solve the myth.

  • Creating a portfolio: By contributing to open-source projects, you build a portfolio that shows your technical writing abilities. Through it, you can build a career or position yourself as an expert in a specific field.

Getting Started with Technical Writing

You have now decided to get started on technical writing and need help deciding what to do next. The tips below will get you going:

  • Find a project that suits you. You can contribute by improving the documentation, creating tutorials, or translating the documents. You can find open-source projects in any of the following repositories: GitHub, GitLab, Mozilla Knowledge Base, React.js Documentation, Bitbucket, etc.

  • Read through the project documentation to understand its goals, features, and user base.

  • Contribute by opening and posting a pull request.

Best Practices in Technical Writing

These tips will help you stay on track and establish a niche once you start with technical writing:

  • Be involved.

  • Stick to a style guide, if there’s one.

  • Have an outline that summarizes the content of the page.

  • Introduce the work you are about to do in the first paragraph.

  • Be considerate of your audience.

  • Avoid repetition.

  • Ask for feedback on how to make improvements if your pull request is not accepted.

  • If accepted, don’t forget to thank the maintainers.

  • Keep looking for and working on new problems.

  • Don’t forget to share your progress!

Important Tools Used in Technical Writing

Here are some common tools used by technical writers:

Sample Projects to Explore as a Technical Writer

Below is a list of projects you can explore. The list includes front-end templates, a computational research platform, and a computing foundation.

Conclusion

In this article, we have explored an introduction to technical writing, explained what open source is, discussed the relationship between technical writing and open source, mentioned the benefits of contributing to open source as a technical writer, and browsed tips on how to get started with technical writing, best practices to abide by, important tools to take note of, and some sample projects to explore.

In conclusion, technical writing holds a very important role in open source, and requests for technical writers have been forecasted to increase immensely in the coming years.

Technical writing Open Sourceguidebeginner