1 of 25

Contributing to open source documentation projects

It’s a scriptorium, not a bazaar

2 of 25

Who am I?

I’m https://github.com/theletterf

Maintainer of OpenTelemetry.io docs
Contributor to other projects

Splunk Observability documentation
Splunk style guide for Vale linter
Docsy theme for Hugo
…and a trickle of minor contributions

Author of a parody repository :)

https://github.com/theletterf/english-lang

3 of 25

What is open source?

Open source is a social setting where the main thing that bind people together is their interest in developing a project. Without people, open source is just coding alone without walls.

4 of 25

In open source, people is everywhere�(You better learn to work with strangers)

5 of 25

Open source is not a contest

There’s only one way of winning at open source, and that is keeping the project alive and stable. You’re doing well if your contributions help sustain the project. All else is noise and statistics.

6 of 25

Open source needs your understanding, not your commits

Open source projects don’t need your "help”. What they need, especially the biggest and most mature, is commitment and understanding. Commits don't matter; finding ways forward does.

7 of 25

What open source does not need

https://blog.domenic.me/hacktoberfest/

8 of 25

What’s in it for you?

The “Of Course”�

You add useful, always available docs samples to your portfolio
You receive feedback from reviewers, thus improving as a writer
You support an open source project, which is a noble thing to do

The “Hey I Didn’t Know That”

You learn how to work with strangers in a remote environment (it’s hard)
You connect with other professionals in the same field. Real networking
You learn different ways of working, documentation tolos, and styles
You develop a thick skin and learn how to distance yourself from work

9 of 25

How to get started as an open source docs contributor

Find a good reason (and a project)
Read the docs and use the project
Start by listening to other people
Make it about helping others

10 of 25

Find a good reason for contributing�(Only then look for a project)

Good reasons include

You use the project at work
You document derivative work
You use the project regularly
You need to learn how to use it

Bad reasons include

You want to build an OSS portfolio
You found the project through “good first issue” search engines
It’s a very popular project and you keep hearing about it
You want to insert your producto docs into the open source docs

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.

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.

11 of 25

If you are already working at a software company

Select projects that your company is actively using or contributes code to, chances are that you’ll find in-house allies and sponsors
Check with Legal or with your open source office (if you have one) before you contribute or sign a CLA (Contributor License Agreement)
If possible, use the same GitHub account for your everything: personal stuff, open-source contributions, work-related contributions, and so on

12 of 25

Become a user and read the docs

If you want to contribute docs, 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.

13 of 25

The Must Reads

The main README file and the one inside the docs folder (if it exists)
The CONTRIBUTING.md guide and the Code of Conduct
Is there a more detailed contribution and style guide? Read it
The license. Are you OK with it? Are you allowed to contribute?

14 of 25

Start by listening and taking responsibility

Join the community channels for the project
Open issues and then own them if you can
Maintain a steady yet discreet presence
Get used to rituals, rules, and customs
Never impose your criteria!

Eager to open a pull request? Make it small and tie it to an existing issue.

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.

15 of 25

Don’t do this

16 of 25

Do this

17 of 25

Make it about helping others

When you help others, you’re helping the project; when you only think about yourself, you aren’t.

Review pull requests: it’s the most time-consuming and difficult activity
Help triage and solve issues
Discuss ideas with contributors
Identify areas of improvement

Ideas for improving the docs will come naturally.

18 of 25

My experience with OpenTelemetry.io

How big is this project right now?

+700 contributors since the beginning of the repo
70 contributors in the last year
Backlog of +250 issues
Around 25 pull requests open on any given day

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.

19 of 25

How I became an approver and then a maintainer

A not so long journey

Become a member of OpenTelemetry in GitHub (you need sponsors)

Then…

Show up in the CNCF Slack channels (#otel-comms)
Show up at SIG Comms meetings (Mon at 10am Pacific)
Contribute with reviews and pull requests (10 to 20)
Being part of a contributing company helps a lot
I happened to be a Docsy contributor already

Rinse and repeat (reliably!)

20 of 25

You can have a look yourself!

https://github.com/open-telemetry/opentelemetry.io/pulls?page=20&q=involves%3Atheletterf+is%3Aclosed

21 of 25

Open source contributions don’t stop at docs

You can contribute much more than Markdown edits:

Improve the CI/CD build system
Improve the theme or template of the docs
Localize the docs (l10n)
Add diagrams or visuals
Devise new automation

If you can improve reach and self-sufficiency, it’ll be a win for all!

22 of 25

Key takeaways

Open source is about people and collaboration, not just code
Contributing to documentation is valuable and impactful
Start by understanding the project and its community
Focus on helping others, not just building your portfolio
Patience and persistence are key to becoming a valued contributor

23 of 25

Your next steps

Choose a project you're passionate about or use regularly
Read the project's documentation and contribution guidelines
Join the community channels and listen to ongoing discussions
Start small: review PRs, help with issues, or make minor improvements
Be consistent and reliable in your contributions

24 of 25

"In open source, we feel strongly that to really do something well, you have to get a lot of people involved." ��- Linus Torvalds�

25 of 25

Thank you!��Questions?