Contributing to open source projects as a Technical writer - The what and why.
As a technical writer, my most remarkable contribution has been the diataxis documentation, and guess what? All I did was delete one repeated word. Yeah, that's right! Contributing to open source is more effortless than you thought.
The second project I contributed to was Igbo API; all I had to do was pronounce some Igbo words.
When we raise a topic like open source, most think it applies to developers. What if I told you that updating a readme file for every project requiring a coding skillset is essential?
This article will discuss what open source is and why writers should contribute to open source.
By writers, this applies to:
Business writing,
Content writing,
Technical Writing,
UX writing,
And any other type of writing done before, during, and after a digital or physical product launch.
This article is for technical writers, but you can replicate these tips for other writing styles, given that the skills are similar.
"Open source is the new Sauce"…….. AceKYD, 2017
Understanding Open source and your role as a technical writer
Contributing to open source is a great way to improve as a writer, help people, and collaborate with global teams to produce quality documentation.
To further this conversation, you must understand what Open source is and the tasks, skillset, and tools required to be a contributor.
What is Open source?
An open-source project is a project with its source code and documentation available to anyone online to access, modify, improve, and share.
In a survey conducted by Open source survey, 5,500 people randomly selected via Github participated to understand the experiences, challenges, attitudes, and backgrounds of people who use and create open-source projects.
The screenshot below highlights the issues encountered in open source.
One of the challenges facing open source contributions and adaptation is the need for more quality documentation.
Suppose documentation affects open source projects with a 93% mark. Why don't we have as many technical writers picking up these projects and contributing to improving experiences?
What kind of tasks, issues, or contributions can a Technical writer make in open source projects?
The kind of contributions you can make to an open source project depends on your skills and what needs to be done.
How?
Start from the onboarding of developers or contributors to set up their machines to contribute to the project. This means you need to write onboarding material to explain to new contributors what the project is about and how they can get started.
Secondly, internal documentation may need to be updated to assist maintainers, contributors - technical writers, developers, and designers understand who made a decision. It also helps to tell why they decided on a product or process and all the necessary information to understand product operations and SOP(Standard Operating Procedures).
Furthermore, external documentation explains to anyone interested in the project what it is about and how they can get started. Imagine not having documentation of your favourite programming language. How do you start with the building if there are no guides? It is the same for open source projects; every project requires documentation that explains how a product can be used.
Other forms of documentation that you can do are:
API Documentation
Tutorials
Whitepapers
How-to guides
FAQs
Blog posts
Walkthroughs, user guides, and knowledge base
Newsletters, policies, and SOP(Standard Operating procedures)
As well as localization (translating docs into different languages), finding typos and grammatical errors, listing them as issues, and helping to fix them.
Sometimes, you may need to gain the skills to work on a documentation task. One of the superpowers of technical writers is "learning on the job." You may only sometimes have the skillset, but you can always learn and help improve open-source experiences.
Skillset and tools required for contributing to open source as a technical writer.
This section covers the skills and tools you need to acquire to efficiently carry out some tasks as an open-source contributor.
Skills required to contribute to open source projects as a technical writer:
Strong communication skills: This is required because you will be working with people from different backgrounds, countries, ages, and orientations. Knowing how to communicate is an essential skill.
Patience, because these maintainers have their jobs and live too!
Docs-as-code approach to documentation: This refers to treating documentation like code, using the same systems, processes, tools, and workflows as codes to manage documentation.
An understanding of Programming: People often ask if they need to code to be technical writers, and I always reply, "How do you plan to explain how to use an API to a developer if you don't even understand what an API is?". To be an outstanding technical writer, you need to understand the basics of code.
Take some time to fill in the technical and writing gaps you have.
Recommended tools to learn as a technical writer
Some skills are required to be a sound technical writer, and others are "good to have". One of the ways I improve my skills is by going online to look for job openings. I look through the description and the requirements and try to build my skillset based on the kind of environment or company I would like to work with.
Here is a concise list of skills you may want to learn;
Familiarity with tools like Git, GitHub, GitLab, and other VCS(Version Control Systems) for collaborative work.
Discord, slack, and other open-source communication tools.
Markdown, XML, Wiki syntax, reStructured texts, Ascii docs, and other common source formats used in documentation.
Docs-as-Code and a strong command of English are requirements for most jobs.
Benefits of Contributing to open source projects.
Most of the time, contributing to open source projects is free, which means you may not be paid any monetary value. Some projects may offer cool swags and recommendations. Still, for the most part, there are multiple benefits of contributing to open source projects, like:
You get the opportunity to work with a Global community. At the same time, you gain experience working with a diverse team and improve your connections.
Improve your Writing skills: Getting feedback from other contributors, maintainers, and the community allows you to write better.
You attract job opportunities.
Contribute to projects that you care about.
An opportunity to learn about new technologies and widen your knowledge.
You can build a world-class portfolio while making a project easier to contribute to and use.
Finding open source projects to contribute to
In finding open source projects, you want to contribute to, I suggest you start with products, tools, and communities you already use or are a part of. This is because there is little or no need for you to learn about the technology since you already use it.
Utilize your social media connections:
Reach out to open sorcerers on Polywork and create a highlight to show your skills and availability on Playwork.
Search for announcements on Twitter.
Search for good first issues on sites like:
These websites make highlighting simple issues easier for first-timers to contribute to open source projects. So, you need to use the filter or search bar to find jobs.
Filters you can use are #first issue, #documentation, #docs, #writing, and other related words.
When you find a project that interests you, check out the readme.MD/ contributing.MD file to learn more about how you can contribute to the project. Every open source project has its contributing guidelines.
Join the community channel on slack, discord, or any provided links and ask direct questions and get help from the community.
When you have successfully acquainted yourself with the project and identified what you want to do, the next steps will be to Fork the project to have a version on your local machine, make edits, and create a Pull Request(PR).
In conclusion
Contributing to open-source projects as a technical writer can initially seem overwhelming, but having a basic understanding of the necessary skills and tools is the first step towards this journey.
Documentation for an open-source project is as necessary as the software itself. Because humans can't utilize what they don't understand, technical writers are just as crucial as software engineers in the open-source ecosystem. You are invited to join this train.
This journey benefits both you and the project you're working on by providing you with seasoned professionals as mentors. In turn, you contribute to a project that helps you and the world.
Connect with open source maintainers, enthusiasts, and contributors on Polywork, Twitter, and other social media platforms.
Resources
Here is a list of valuable resources to guide you in this journey:
My list of technical writing resources
Thank you for taking the time to read. I hope this article has been helpful, and if you have any questions, don't fail to reach out to me via Twitter.
May the sauces be upon you.