Enabling Teams to Write Strong Documentation
Part 3: The Implementation
One of my passions is documentation, a task that poses challenges for many companies and projects. At RigUp, I was challenged to find a way to aid our developers in improving documentation practices and quality. You can read about the first part of my journey in Part 1, and the system we chose to implement in Part 2.
Once I had a plan for a system to implement, the actual work of making it happen began. I built a small working group of invested technical leaders from the company and presented my ideas.
Of course, that’s when it got much, much messier than the nice simple plan.
#docs-working-group
We met for the first time just a few days after the formation of the group, which included developers of different skill levels who had a vested interest in improving and refining documentation.
1. What’s the difference between tutorials and how-to guides?
While this had initially seemed clear to me, in practice the art of drawing the line between a “tutorial” (requires no prior knowledge) and a “how-to guide” (answers a question you need to be familiar with the codebase to ask) proved more difficult than anticipated. People came with pre-conceived ideas around what a tutorial was and wanted to make everything a tutorial, even if it didn’t fall within the definition we had decided on for “tutorial.”
2. Why can’t we just use automated documentation tools?
An obvious way to improve documentation is to make it so that developers don’t have to write it at all. During our working group sessions, we discussed the necessity of maintaining a Storybook instance for presentational components and proposed using tools like Swagger to automatically generate documentation of our APIs. Initially, this seemed at odds with our goal to maintain all documentation in a single source, but the benefits of utilizing these tools were substantial. They enable the creation of instantaneous, living documentation that requires little to no maintenance from developers, which was one of our primary goals.
There was a lot of scribbling on the board.
Once we had cleared up those questions, we ultimately decided that each category would live within its own directory in Confluence (directory structure to be further refined in a later meeting). With that out of the way, we were able to move on to figuring out a handful of templates we wanted to create as a starting point.
We also briefly delved into more complex categorization, particularly how we would tie together documentation regarding a specific feature or tool that spanned more than one of the four categories. For our purposes, we decided to use Confluence’s tagging system to tie together documentation across function/type, but keep it organized within the strict directory structure based on the four categories.
Another takeaway was that we only really wanted one tutorial per codebase/per project that required setup. This meant one for our main app, one for our mobile app, and a few for small projects that tied into our main apps. Accordingly, we decided to restrict the creation of tutorials after the initial release.
In order to support and focus on our goal of making quality documentation easy to produce, we also decided to continue to utilize external automated documentation tools, but we would require that they be linked from Confluence in order to ensure that the information remained easily discoverable.
We reconvened a few days later to resolve some of the remaining unanswered questions (and after we’d had time to come up with some more). In this meeting, we focused on the specific details of housing this documentation in Confluence and assigning owners to outstanding tasks/questions. You can see from our board some of the continuing discussion on what belonged where.
After closing out those discussions, we created a shared Google Drive folder and began the first drafts of our templates, with a specified goal of reviewing them in two weeks. We had one additional meeting to clarify a few points around writing the templates and what they should contain, as well as following up on other to-do items, as everyone began to write their drafts.
The Catch
As we worked together on these templates, a larger question arose: what were we going to do about the documentation we already had? Obviously we wanted to capture it in this new system or we’d fail to address one of the primary reasons we adopted it to begin with; the question of where documentation could be found. Our documentation was spread between an in-app tool, Storybook, a documentation tool other than Confluence, and a few random folders on Google Drive. While I could have spent a few weekends and corralled it all, I certainly didn’t want to.
I decided quickly that this was the sort of task best crowdsourced to the entire team. I set up a come-as-you-please event in our company kitchen, complete with a Spotify playlist called “Happy Morning” (which turned out to be surprisingly melancholic) and developers dropped in to hang out and work on migrating documentation over as they had availability. Some doubters were concerned that people wouldn’t show up, but bribing attendees with a pizza lunch and prizes helped.
The Release!
Over the course of about four hours, 80% of the team was able to stop in and knock out some of the documentation. By the end, there were only five documents that hadn’t been transitioned, which we were able to pick up over the next couple of days. We kept track of who had moved each document and awarded buttons to the top three contributors. Most importantly, we asked that documentation be deleted or archived once it had been added to Confluence.
In the end, the documentation wasn’t perfect or perfectly up-to-date, but it was in the same place, categorized more or less correctly, and ready to form a pillar of our engineering team. Of course, that left the larger, looming task of cleaning up the documentation and ensuring future documentation complied with our new system and standards.
The Guild
To help us maintain these established standards around documentation, we formed a Guild, after the well-known Spotify model. More about that in Part 4: The Guild…
