The Write Stuff: 3 Lessons I Learned from a Tech Writing Hackathon

The Write Stuff: 3 Lessons I Learned from a Tech Writing Hackathon


3 min read

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

Willow Smith is saying "Class is in session"

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! ๐Ÿ˜Š

Penguin say next

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.

On a black screen, the phrase "Keep The Balance" appears

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! ๐Ÿ˜œ

Schitts matriarch is saying "When ONE of us shines, ALL of us shines".


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! ๐Ÿ˜Š

Fireworks explode as the phrase "The End" comes on screen


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

Did you find this article valuable?

Support Christine Belzie by becoming a sponsor. Any amount is appreciated!