Community Contributions and Documentation

I want to share what I’ve learned about community contributions to Git repositories.

Actually, I talked about it the other day with @Ray Paik of @PingCAP, as part of their podcast series, Data in the Hallway.

I’ve contributed to open source Git repositories. I’ve participated in hackathons. I’ve helped run hackathons.

In my first hackathon, I wanted to learn about @Docker. They ran a meetup for their second birthday. I tried setting up Docker on my Linux laptop, using their “Getting Started” docs. I got a bit frustrated. So instead, I fixed some typos. I got a T-shirt that would have looked cute on a two-year old 🤣 . (Heck, I was proud of it, so I actually wore it to work the next day.)

After joining GitLab, I helped run a couple of hackathons at a conference, and in cooperation with a Technical Writing program.

I had set up issues based on errors generated with Vale (https://vale.sh). People happily contributed, because they wanted to learn Git. We could have addressed the errors ourselves, but we wanted people to think of GitLab when they work with Git. But we had to:

• Set up each user. Share docs on the process with each user. Explain if/as needed.
• Evaluate the Merge Requests (aka “Pull Requests”).
• Merge valid fixes.

Yes, this took work. Yes, this saved us the time we would have used to make the same fixes. Was it worth it? Maybe, since we wanted people to think of GitLab when they use Git.

In a couple of cases, contributors went further. They rewrote part of our content for readability. That was valuable!

Back to my podcast conversation with Ray. He asked about open source contributions. What does an OSS group want from contributors? I’ll split that into three categories:

• Typos.
• Rewrites.
• Software evaluations. When you try new software, find their “Quick Start” or “Getting Started” guides. — If the the guide works perfectly, great! You have software that you may want to use. — If you see problems, open an issue! Even better, if you have a solution, open a Merge or a Pull Request. They’ll thank you, as you’ve evaluated their docs (and more importantly, their product) from the point of view of a potential new customer.

Gosh, I could create blogs in each of these categories! In the spirit of best practice Technical Writing, I won’t promise posts in these areas in the near future.

Here’s the YouTube podcast: