Finding Our Rhythm - A Creative Approach to Documentation Woes

Over the past few years, I’ve had the opportunity to work with many talented engineers at a few different companies and one thing I’ve observed that unites us all is documentation woes. It’s challenging to work within a company that has weak, disorganized, or MIA documentation.  It can even make you wonder if you have made the right choice after joining a team.

It’s tempting to outsource this burden to libraries, tools, and automation (in the name of efficiency!) or just to give up and do the bare minimum; throwing together random unstructured READMEs containing the necessities and opting to onboard engineers through pairing and 1:1s. This approach does have some benefits and can work in the short term - but when a company scales as rapidly as we have the past year, that IOU for tech debt comes knocking and new challenges and complexities appear.

Out of Key

One of the things to love about our remote-first culture at Vouch.io is the high amount of agency we have and the freedom and autonomy that this encourages. However, as we scaled, the desire to respect one another’s work-life balance combined with being distributed across time zones  meant that it was harder to stay in sync . It’s tough to ping your colleague for a quick question when it’s 3 am for them!

The peak of these issues occurred when during a retrospective, documentation woes were the main source of frustration among the team. Originally considered a tooling issue, closer examination illuminated a deeper problem. For the most part, people knew what information needed documentation, but hesitated when considering how to get started, which format to use, who the target audience was, or where to put (or find!) the documentation within the tools. I recognized that we needed to be able to work with a minimal amount of friction, asynchronously and “on our own time” while also ensuring that we deliver a quality product to our global clients on time.

At first, I wasn’t sure where to start. How was I qualified to solve this problem if a team with decades of experience was still struggling? What could I offer? What do “good docs” even look like?

Well, I know I trust my team. Could I start by asking them?

I put together a poll asking Vouch.io team members to share their favorite documentation. I started to notice patterns within these artifacts. I could recognize that in well-structured docs, certain frames are provided that help to shape the expectation of what a reader can gain from the material. These frames add meaning and context without changing the meaning of the underlying message. Restructuring based on the needs of the user naturally separated technical literature into levels of tolerable complexity.

I realized that it was this shared frame (of audience expectation) that not only provided valuable context to the reader by relieving them of some of the semantic burden but using frames like this also reduced the scope of the answers that the author was required to provide for every piece they arranged. I then considered the other piece of feedback we got in our retrospective session. Our teammates were eager to spend more time with one another.

So we needed to:

1. Unite around a shared frame
2. Hang out and have fun

What about a workshop? That’s when “DocFest” as an event was born.

In Tune

Over the course of 2 weeks, Vouch team members were all able to participate in a 4-hour workshop that included an introduction to the Diataxis framework and 3 group activities. The intention behind the event was for all of us to “participate in an experience that gives us a shared understanding of how to produce high-quality technical documentation.” The expected outcomes were:

1. Shared understanding of the different types of documentation (4 doc model)
   • Frames based on audience awareness - who benefits from each document artifact?
2. Documentation artifacts are consistent in format and easy to find and update.
3. Maintenance schedule- "Always complete, never finished"
4. Improved onboarding experiences - Start point for Engineering Handbook

In small groups of 4-6 teammates we demonstrated our knowledge of our new shared frame, through musical metaphors, silly stories, and by playing games using pictures of Vouch teammates’ dogs. By dreaming up use cases and fictional(ish) personas we put ourselves in the seats of the audience members that we were trying to compose music for. As a final twist, we plotted these stories onto an effort/impact matrix that eventually revealed to align with the Diataxis frames.

As a last activity, every participant took ownership of one of those user stories as a starting point to compose a new piece of documentation, empowered with a new shared construct, we united behind the context of these shared frames. The event resulted in close to 20 new technical artifacts. Beyond the immediate outcomes soon we learned that the new shared frame proved beneficial even beyond what we would think of as “traditional” documentation.

Rhythm

Have you ever been asked to review a PR with 35-pages of changes? It’s hard to recognize whats really going on and not have your eyes glaze over. Now, armed with this new shared language instead of a 35 page Pull Request, we were able to attach human meaning leveraging the language constructs we now all shared. After developing a new feature, Vouch Software Developer Vinícius Picanco communicated the relevant changes via our internal wiki and attaching as a link to the PR. Our team leads were able to understand the inner message without parsing a long commit history or a code diff that lacked context. It put a smile on my face when in our company discord I saw our team lead exclaim “wow great work! thanks for the write up, looks like that docfest really works!”.

Beyond the feedback survey that most folks completed, it was this exchange that finally confirmed my hypothesis that the secret to creating high-quality technical artifacts is by coming together to leverage the power of shared language to create recognizable patterns. A pattern, much like rhythm, helps authors and readers understand the human meaning associated with code or notes. I now believe it’s vital for development teams to create a unified sound or risk an unrecognizable rhythm.

🎼 These patterns can certainly come in the shape of a framework or library but which frame your team unites around isn’t as important as the process of collaborating to create consensus. When everybody plays a part in the symphony of documentation, the harmony it creates is powerful.

Harmony

Just like a symphony, successful documentation requires a harmonious blend of technical details and human touch. It's tempting to take out a tech debt loan against your team or to rely solely on automated tools, but by doing so there is a risk of creating a cacophony of information that overwhelms and frustrates your team. It's like playing a piece of music with all the instruments out of tune and out of sync - it's an unpleasant experience for everyone involved.

The solution is simple: invest in your people. By fostering communication within a team to construct a frame of recognizable patterns in documentation, we created a coherent and meaningful record that reflected a recognizable rhythm for all. When we did this, it enabled Vouch team members to come together to perform our masterpiece- something greater than the sum of its parts.

In the end, it's all about creating an enjoyable and seamless experience.

—

Software engineers Jordan Miller and Heather Haylett understand the importance of striking the right balance between technical accuracy and human understanding. They will share their insights on this topic at the 2023 Clojure Conj in a session titled “Find the Write Rhythm for Your Software Composition”.

Attend their session to gain a deeper appreciation for the importance of integrating recognizable patterns and human frames in your technical documentation while learning how we created practical strategies to infuse our documentation process with the right amount of humanity.