This Release Party featured balenistas banding together to improve the balenaCloud documentation. We explored how our team or the community could contribute to the docs, and made a little contest out of it while learning a few things along the way.
What’s a release party?
Our team gets together every once in a while to sprint on releasing a new feature. This particular party was a bit different with its mission to improve documentation. To make it more interesting and to involve our community, we stream it live. It’s a fun celebration of work and a spotlight on how well we can collaborate as a remote, international team spanning multiple timezones.
It’s very interesting from a community perspective as well. Everyone gets an insightful first-hand view into our internal workflows, tools, and processes to figure out the challenges our customers are facing while always reducing friction for fleet owners.
Use the embed above or watch the recent Release Party on YouTube.
Why did we focus on documentation?
Documentation is an integral part of our products. They’re the single source of truth for our users on how to get started, learn more about and use features, and how to get the most value out of balena.
Our goal for the party: to identify issues and fix them (whether big, small, or any size in between) to keep our documentation in the best possible shape.
We focused on:
- Missing or outdated documentation for balenaCloud that needed care
- Identifying friction in the documentation & open-source contribution process at balena
- Finding ways to automate or auto-generate repetitive sections
- Encouraging collective ownership of the docs to boost contribution by the entire team
This, like many objectives at balena, leads to a win-win outcome.
Making it a competition
To spice things up a bit more, we held a little internal competition to see who could contribute the most to our docs effort. We created a scoring schema that took into account issues created and different levels of issues solved.
Whether lightly technical or deep into engineering, any balenista could significantly contribute for a chance to win a prize (gift cards for food– who doesn’t love food??) Scoring was, in fact, tracked by a device running on balena. Our teammates had a lot of competitive fun with this part of the Release Party.
What did we learn?
The nearly eight-hour release party on 19 Friday March 2021 ended with 65 pull requests being opened resolving over 69 issues. We opened 47 new issues to track further changes and improvements that were needed. We deployed and discussed several issues that were stuck in the pipeline.
Docs can be a teaching tool
Another goal of the Docs Release Party was to motivate teammates to learn more about GitHub and how to create pull requests more easily. It was a great event to teach version control skills and thinking that can be valuable today and tomorrow, as git and GitHub start to intersect different domains and fields.
During the event, we welcomed various teammates to join the stream to troubleshoot or review their work. This way, everyone could learn from each other and about the overall process.
GitHub UI was the tool of choice
The GitHub UI editor enabled many teammates to make smaller changes to the documentation. Most of our contributors used it as their tool of choice to create pull requests for the 200+ issues we prepared for the Release Party.
The issues in the documentation repository were pre-classified into several categories according to difficulty level, amount of context needed, and amount of investigation required to solve them. The time spent triaging and creating the project board helped contributors find the issues that they could solve faster. With the automation GitHub provides in the projects section, we were able to manage and track the release party with ease.
Improving our CI/CD tooling
We identified some internal workflows we follow at balena that generated friction in the contributor experience. One particularly being semantic versioning requirements that helps the CI/CD system automatically version the code/docs according to the change-type present in the commit. While helpful for automation tools, it can be clunky for first-time contributors. We took this to heart and are working on ideas to smoothen this process for everyone.
From a CI/CD perspective, the Release Party was a great way to stress test our system. It turned out when 20+ PR’s were concurrently being reviewed and merged, conflicts & outdated branches were a by-product bound to be generated. For situations like these, our versioning automation tool (aptly named versionbot), comes in clutch to automate common processes like rebasing, re-testing, and self-approving PR’s, etc. Automating away more redundant tasks will help improve the overall workflow.
Closing thoughts
This Release Party helped many folks take the first step towards contributing to balenaCloud documentation. We created pull requests, resolved issues, and most importantly, had the entire team work together made it even more enjoyable.
The release party crew even went the extra length to guide fellow balenistas in resolving issues, making pull requests, and doing reviews all live on stream. We believe that’s what release parties are all about. Balenistas getting together on work day having fun, doing what they do best!
Thanks to everyone from the team who helped to make the release party #4 an overall success! We couldn’t have done it without you.
Get involved
Apart from the improvements in balenaCloud documentation through the release party. Our core efforts will effectively go into improving the contributor experience to balena’s repositories.
Over the next couple of weeks, we will be working on how to reduce friction for new contributors whether they are folks trying to fix something as small as a typo or adding a feature to the product. Being a largely open-source focused, this gives you an opportunity to contribute as well to any of our open source projects and provide feedback on the features we build.
We will see you all during for Release Party #5!
