Welcome back! 😊
Hey there, open sourcer! 😊 I heard your utility toolkit has improved your PR-ing skills. Congrats! 😊 But before you go back to conquering more repositories, remember the importance of documentation. It's like the "Welcome Sign" to your favorite ride at an amusement park. Without it, an open source project is just a mystery box waiting to be opened. Now before you go back out there and start PR-bombing, there are some tips that I learned from other open sourcers at a tech writing hackathon in the land of Gitlab, so grab your keyboard and some snacks because
1. Grammar is important
Remember all those times you rolled your eyes and scoffed at your high school writing teacher when they told you grammar is important? Well, it's time to send them an "I'm sorry" email because it turns out they were right all along. I was reading through files about troubleshooting a program called Geo and noticed that most of the directions were written in future tense and based on what the issue pointed out, it was recommended to change them to present tense so that contributors have a better understanding of how they can use Geo effectively. Now, grammar is only one of the many things that you need to consider when working with an open source project’s documentation. Onto the next one! 😊
2. Keep it Balanced
Remember when I told you that I used to shy away from open source contributions due to thinking that you’d have to be a coding genius to do it? Well, the documentation played a role in that. It was bogged down by some much tech jargon that I felt was reading a spell in Parseltongue (for non-Harry Potter fans, this is the language of snakes and serpents). So, whenever you’re contributing to a project’s doc, it helps to write in a way that both tech and non-tech contributors can understand when they want to do PRs on a project. When I worked on GitLab’s documentation, I would do something simple as shortening sentences or using more causal language because let's be real, we could all use a little less jargon in our lives. 😉 Ah don’t just go yet. Keeping things balanced in writing is one thing but it’s a whole other thing when it involves working with other tech writers.
3. There’s no “i” in team
Doing PRs on documentation can be overwhelming, so it's always better to have a second pair of eyes. Plus, you never know, they might even have a better meme game than you do. 😂 When I was assigned an issue to edit multiple files, I thought I could handle it on my own. But when one of the lead tech writers added more edits, I realized my limits and asked for help. After several failed attempts, we finally found a solution that worked...create an MR for each suggestion. Remember, in the world of documentation, two brains are better than one. And who knows, maybe together you'll come up with the next best documentation meme! 😜
Conclusion
Congratulations you’re officially a documentation whisperer! 🎊🎉 Remember, the documentation is the “Welcome Sign” of an open source project, so treat it lightly. If you want to learn more ways to be an open sourcerer, be sure to click on the follow button on Hashnode and connect with me via my other socials via LinkFree. Now go forth and make magic! 😊
Credits
Balance Lovers GIF by Bilanz Lounge
Laptop Image by Nick Morrison on Unsplash
Penguin GIF by Eugene Kong
Shining Schitts Creek GIF by CBC
The End Airplane Movie GIF by Filmeditor
Willow Smith GIF by Red Table Talk