I’ve recently become a docs maintainer for OpenTelemetry, a pretty big open source project. As I often receive questions on how to start contributing to open source docs, this seemed the right time to write about it. Let me tell you how I started and progressed, and what you can do to start your open source documentation journey.
My current job requires quite a bit of knowledge around OpenTelemetry, which is an open source collection of APIs, SDKs, and tools for instrumenting software. Most of the engineers I work with contribute or review code for OpenTelemetry projects on a regular basis, so most of the features I end up documenting either originate or will be contributed back to open source. In that context, I thought that contributing documentation to open source could be at the same time a learning opportunity and something that produces long term benefits for the docs I write at work, as the features are in most cases derived from upstream. Working on open source documentation would help me prepare for upcoming changes in the product documentation.
With this in mind, last year I sought to contribute to the open source documentation of OpenTelemetry. Open source collaboration wasn’t new to me, as years ago I had contributed a couple of features to Docsy, the Hugo theme developed by Google. As it happens, Docsy is the theme used by many docs projects of the Cloud Native Computing Foundation, such as Kubernetes and… OpenTelemetry! I started by doing reviews and small edits, which allowed me to learn about the project workflows, the docs stack, and the ways of the maintainers. At the same time, I joined the Slack channels where docs maintainers and contributors hang out. Through steady activity and dedication I managed to involve myself more.
Dedicating time to open source is something valued and encouraged by most tech companies these days, although it’s a little less common in case of tech writers. In my case, I asked for – and got – permission to dedicate a maximum of 25% of my work time to open source, like engineers do. This allowed me to focus on deeper open source work, which in turn improved my standing with the community. With an increasing volume of work (OpenTelemetry docs started four years ago), I was promoted to maintainer as a recognition of my continued efforts and as a way of encouraging me to contribute even more. In case you’re wondering, becoming a maintainer for OpenTelemetry requires a simple vote and a pull request.
How did I get there?
Having a good reason for contributing to open source documentation is the most important ingredient in your journey. Perhaps you’re using an open source project at work, or at home; maybe you’ve been asked to dig into a new open source piece of tech as part of your job; or you care deeply about an open source project and its mission.
Any of the previous reasons translate to care. If you don’t care about an open source project and its mission, if you don’t need it for anything, steer away from it. Don’t go and pick a random open source project and think about contributing to it if you don’t feel any sort of attachment or relation to it. There has to be a link.
Good reasons for contributing include:
Bad reasons for contributing include:
You can’t contribute to a community project if you’re not part of the community. All it takes to become part of the community is to become a user, which leads me to the next point.
Before I started contributing to OpenTelemetry docs I had already used it to instrument demo applications, experimented with its components, and even written a children’s book about it. Still, my knowledge of OpenTelemetry, a complex and heavily technical project, was far from optimal. I wanted to dig more into the core concepts and test different use cases. Improving the documentation, in this sense, was the perfect excuse to deepen my knowledge.
In an open source project there’s nobody to onboard you except the community and what documentation is at your disposal (and sometimes that’s just a README file). If you want to contribute documentation you must put your lab coat on and be prepared for lots of experimentation, failure, and frustration. Writing open source docs is an exercise in patience and self-learning. The reward is that you might become the first in cracking a puzzle.
It doesn’t really matter whether you come from a big contributing company or are opening pull requests from your house in the mountains: when open source projects are well governed (which is the case of OpenTelemetry, for example), contributors must abide by the same rules and follow a certain code of conduct. This also means that you need to pay a lot more attention to the local customs and rituals.
Anything from how the docs are built to how issues are handled to who takes care of what is part of what you need to learn before you can contribute meaningfully. Some of this you can learn on the go, while trying to contribute. Other rules will be available in the Contribution guide (if it exists) or you’ll be able to glean them from past activity. When you enter a community you’ve to learn its language and listen a lot.
The goal for any community-driven open source project is to grow through enhancing and promoting contributions. You want more people to contribute, and you want better contributions, which means more competent eyes, more feedback, more useful and relevant content, or even less content if the one that exists is distracting. When you help others in achieving this, you’re helping the open source project; when you only think about yourself, you aren’t.
Writing is only a fraction of your contributions as a technical writer in open source. I spend most of my time reviewing pull requests, assisting folks in issues, and discussing ideas with other contributors. As part of the ecosystem you want to make newcomers feel at ease and mentor them in their docs contribution journey as they learn about your reviewing standards. Once you do this, your chances of improving the docs will come almost automatically.
It’s about helping others, not about owning pull requests.