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 not as complicated as it seems.
When we raise a topic like open source, most people think it applies to just developers. What if I told you that for every project requiring a coding skillset, it is essential to update a readme.md file.
More on how writers can contribute to open source below.
What do we mean by "writer"?
When lots of people say writers, it could be :
- 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.
Quote: "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?
Open source refers to something people can modify and share because its design is publicly accessible. An open-source project is a project with its source code and documentation available to anyone on the internet 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.
It is not very surprising to see that one of the challenges facing open source contributions and adaptation is not available or poor documentation.
If documentation affects open with a 93% mark, why don't we have as many technical writers picking up these projects and contributing to making experiences better?
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 is dependent on what skills you have 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.
Internal documentation may need to be updated to assist maintainers, contributors - technical writers, developers, and designers in understanding who made a decision and why they decided regarding a product or process and all the necessary information required to understand product operations and SOP.
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 procedures.
As well as localization (translating docs into different languages), finding typos and grammatical errors, listing these errors as issues, and helping to fix them.
In some cases, you may not have the skills to work on a documentation task. However, one of the superpowers of technical writers is "learning on the job." You may not always have the skillset, but you can always learn and help make open-source experiences better.
Skillset and tools required for contributing to open source
This section covers the skills and tools you need to acquire to carry out some tasks as an open-source contributor efficiently.
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 lives too!
- Docs-as-code approach to documentation: This refers to treating documentation like code by using the same systems, processes, tools, and workflows as codes to manage documentation.
Recommended open source tools
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.
Benefits of Contributing to open source projects
The majority 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, but for the most part, there are multiple benefits of contributing to open source, like:
- You get the opportunity to work with the Global community while you gain experience working with a diverse team and improve your connections.
- Improve your Writing skills: Getting feedback from other contributors, maintenance, and the community allows you an opportunity to write better and for a global audience too.
- You Become a better technical writer by learning new skills and tools required for each project: Given that each project is unique, you gain experience using several tools per project.
- You attract job opportunities.
You have a shot at building a world-class portfolio while making a project easier to contribute to and use.
Finding open source projects to contribute to
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:
- Github
- First contributions
- Up-For-Grabs.net
- Good first issue. dev
- Good first iussues.com
- opensourcefriday.com
These websites make it easier for first-timers to contribute to open source projects by highlighting simple issues. 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.
Why contribute to open source as a writer?
Contributing to open-source projects as a technical writer can seem overwhelming at first, 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 probably 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, and 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, and in turn, you contribute to a project that helps both you and the world at large.
Connect with open source maintainers, enthusiasts, and contributors on Polywork, Twitter, and other social media platforms.
Even more open source tips
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.
Now you have successfully acquainted yourself with the project and identified what you want to do. The following steps will be to Fork the project to have a version on your local machine, make edits, and create a Pull Request(PR).
A list of valuable resources to guide you in this journey: