This week, I interrupt your regularly scheduled programming of technical writing techniques to brag about the incredible people I work with, who exemplify a company-wide culture of good documentation.
Let me give you some context: As most of you know, I work as a Senior Technical Writer at Cockroach Labs. For a major product release coming up in April, we had around 163 open issues to be documented for the release. Some of the issues were big-ticket items while a considerable number of issues were small but time-consuming fixes. It wasn’t humanly possible for our team of 4 technical writers to document all the issues before April. While brainstorming possible strategies to complete the documentation tasks, we thought of enlisting the help of our fellow Roachers* to contribute to our docs. The Engineering team had previously organized a successful Bugs FixIt Day, so we decided to replicate their model and announced a Docs FixIt Day.
We planned and prepped for days – announcing the Docs FixIt Day at the weekly team meeting, sorting through the issues and marking the ones we thought the engineers can take up, and of course arranging for snacks. Our fearless leader, Jesse Seldess, brought delicious Babka, and my fellow tech writer, Lauren, baked out-of-the-world, drool-worthy cookies.
We started the day with Jesse’s “Getting Started with Docs” presentation. He discussed the purpose of the FixIt Day, walked the engineers through the Docs toolset (GitHub and Jekyll), and announced the prizes – a Docs-team authored poem** and an Amazon gift card. The prizes would be given to the person who resolved the most Docs issues, and also to the person who resolved the Docs issue with the biggest impact.
We had 24 people in attendance for the kickoff session – in office as well as remotely. At the start of the day, we had 83 open issues marked as FixItDay. The participants included interns, engineers, engineering managers, and our CEO as well! They self-assigned the issues they wanted to work on and wrote docs all through the day till 6 PM. The last I checked on the day, we had 52 open PRs ! And people were contributing PRs even after that, so the final count might have been higher. (IMO, Jesse deserves an award for reviewing all the PRs).
To say the day was a success is an understatement. Not only did we get a big chunk of our documentation done, but the event also fostered cross-functional team collaboration. The engineers’ enthusiasm was infectious – they were totally invested and involved in the whole Docs process. We had given them the option of either working on the Docs end-to-end (as in they write, edit, revise the content), or just provide the raw content and the Docs team takes over the PR for them. But almost all engineers opted to complete the docs themselves, asking us for assistance with our GitHub process and SQL diagram generators and so on. This gave them a chance to understand the Docs toolset and they voluntarily helped us figure out how we can optimize the toolchain.
I have never been prouder to be a part of a company as I am now. As a technical writer, I am intensely aware of how big of an anomaly our company culture is. In most companies, docs are added as an afterthought and technical writers are considered a pesky annoyance. At Cockroach Labs, however, the importance of good, sound documentation is deeply ingrained in our DNA. And that is evident in all forms of documentation we produce – RFCs, user docs, training materials, or even meeting notes. That is also evident from the fact that we already have a team of 4 technical writers for a team of around 35-40 engineers, when it is not unheard of at other companies to have one technical writer for 120 engineers. It is a privilege to work at a company where people genuinely care about good documentation and are willing to do everything they can to ensure we maintain the quality documentation we have. And I am thankful to be a part of an immensely talented team that is rooted in our core values: “Aim High and Build to Last”.
You can check out the awesome work our team did for Docs FixIt Day here.
*Roachers n. People who work at Cockroach Labs
**Poems written to express our appreciation for our peers is a time-honored tradition at Cockroach Labs.