If you want to contribute to an open source software (OSS) project – or to run a docs-based hackathon, great!

But before you start, ask yourself “Why?”

Do you want to add to your resume? Do you want to get help from your open source community? Both are laudable goals.

Let me suggest a bigger goal: help that project sell their product.

Actually, I talked about it the other day with Ray Paik of PingCAP, as part of their podcast series, “Data in the Hallway” (https://lfnkd.in/gNn6zNdW).

I’ll let y’all know when Ray publishes our podcast, scheduled for November.

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, Inc. They ran a hackathon at meetups 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.) I continued to contribute when I had time.

After joining GitLab, I helped run a couple of doc-based hackathons. One at a conference, and another 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 it required prep. 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 time. Was it worth it? Maybe. It did help make our docs look more professional. And we wanted people to think of GitLab when they use Git.

In a couple of cases, our 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. (Fix a typo. That’ll help the project look more professional.)

• Rewrites. (Improve the readability of a project’s docs. It’ll help them keep their users interested.)

• Software evaluations. Try new software based on a project’s “Quick Start” or “Getting Started” guides.

— If the the guide works perfectly, great! You have software that you may want to use, tested by target users like you. Good projects will be grateful.

— If you see problems, open an issue! Even better, suggest a change with a Merge or a Pull Request. They’ll thank you, as you’ve evaluated their docs 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 will not promise to blog about these topics in the near future. 🤞