Enabling Teams to Write Strong Documentation

Part 2: The System

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: The Journey.

Once I realized I needed to develop a system that enabled developers to write documentation as quickly and painlessly as possible, I was able to completely reframe the problem. I talked with my team, reviewed my prior research, and identified three key challenges that individual developers faced when writing documentation for a team:

1. Knowing what to document
2. Knowing how to document it
3. Knowing where to find existing documentation

It had been easy to find opinionated articles and templates telling me how individual people should write documentation, but as I began to research answers to these new questions, I found far fewer resources.

Photo by Nathan Dumlao on Unsplash

Then I stumbled across Daniele Procida’s article, What nobody tells you about documentation. In it he discusses a method of organizing documentation within four categories, each of which should exist in separate, distinct locations. I highly recommend reading the article for an in-depth exploration of his approach to writing documentation.

To briefly summarize, he categorizes documentation along two axes into four categories:

Functions of documentation by Daniele Procida / Chart by Chase Clark @ RigUp

1. Tutorials: Oriented towards learning something new
2. How-to Guides: Oriented towards achieving a specific goal
3. Reference: Oriented towards providing specific information
4. Explanation: Oriented towards increasing understanding of something

This gave an easy, established system of categorizing documentation. However, I still had to answer the question of how we were going to get developers to move from staring at a blank page to quickly producing quality documentation.

I spent a few lunches by the lake, roasting in the Texas heat, trying to figure this one out.

The answer, when it finally came to me, was painfully obvious and simple. All of those articles I had read about individually writing documentation held the key. Many had included a template for “good” documentation — in fact, some had been little more than that. If we just had templates for our most common documentation tools/features, we could massively reduce the pain and effort for our developers.

With the how answered, I was finally able to propose a plan:

The Plan

1. Identify relevant categories from Daniele Procida’s system: Tutorials, How-to Guides, Reference & Explanation.
2. Decide on a location for each category of documentation.
3. Build the necessary tools/spaces for documentation accordingly.
4. Define and provide templates for most commonly documented tools/features.
5. Communicate the plan to our team and roll it out.

With my roadmap in place, I was ready to roll up my sleeves and get to work.

(To be continued in Part 3: The Implementation…)