How to champion investments to improve documentation

This interview is part of our Fieldnotes series, where we research what leaders are doing to improve the effectiveness, efficiency, and happiness of their engineering teams. ‍

We recently interviewed Aaron Suggs who was previously Director of Engineering at Kickstarter and then Principal Software Engineer at Glossier, and is now starting his own software business. He’s written about ‘build vs buy’ decisions for LeadDev, and ‘What a deploy bot taught us about documentation’ for Increment, and continues to write on his personal site. Below you’ll find his practical advice for spearheading investments in improving internal documentation. 

Define the business case for investing in documentation

Engineering documentation in and of itself is not an important business outcome. But there’s always a business outcome that improving developer documentation can help support, and we have to frame the investment in a way that aligns with that goal. 

Take refactoring as an analogy: if an engineer says they want to refactor something, it’s good to ask them “to what end?”. Because there should be some business-focused reason — maybe “I’m refactoring this to make it extensible for new features” or “to make it more scalable” or “to make it more reliable”. 

Documentation is a means to an end, just like refactoring.

Investments to improve technical documentation are usually about sustaining or improving developer velocity. The business argument is that with better documentation, developers can quickly find the information they need to complete tasks or make better decisions. 

That’s a good start, but we should be more specific. Some examples of reasons for improving documentation might be:

• Getting new hires up to speed faster. You hire a new employee, but how do they get up to speed without having to ask other team members or figure things out on their own?
• Responding to incidents faster and shortening downtime. When things break, how do people fix them quickly? Is there a documented playbook that gives information on how to restart the thing or change some configuration? What’s the customer impact if I make a certain change?
• Protecting the business from vendor disruptions. If a system or vendor suddenly shuts down, do we have documentation around how we use that vendor, where the data goes, and which systems touch it? If we do, and if it’s up-to-date, we’ll be able to come up with a plan for addressing the disruption much more quickly. 

Create a project brief for the proposed change

It’s worth noting that if people don’t feel it’s their responsibility to bring documentation up to date, any investment in improving docs will quickly become irrelevant. For the investment to be durable, it’s important to have an executive sponsor who says “we value this” and then continues to nudge everyone.

A good first step for making a change to your documentation process is to create a project brief. Project briefs outline why we’re doing a new thing and what the new thing is. They cover:

1. The goals of what you’re trying to do
2. “Non-goals”, so what we’re not trying to solve (Let’s say you’re moving to a new vendor. You’d say “our goal is to use a reliable vendor”, and the non-goal might be “to rewrite the system entirely”. You’re just doing a band-aid solution, not a full rethinking of how to solve something.)
3. Possible ways this could be solved
4. Key decisions or tradeoffs (For example, in a build versus buy conversation, the key tradeoffs might center around the different vendors — “the best vendor is super expensive” but “the most affordable vendor is not a complete solution for us”. And “we could build it ourselves but the opportunity costs are high”. Sometimes we go into this with a decision in mind, but still going through the exercise of talking through the tradeoffs of different solutions is a good exercise to clarify thinking.) 

What to consider when choosing a solution

There are two experiences to think through to explore solutions to the problem. 

Consider the authoring experience. Aim to make this as low friction as possible. Think about something like Google Docs or Dropbox Paper: writing in those tools is like writing on a sheet of paper. It’s frictionless. That’s how easy it should be. 

There are other tools where you need to learn markdown, or that require you to click a publish button that creates a pull request and so on. These processes are far too complicated and make it much harder to get people to adopt the habit of contributing to docs. 

Slab, Notion, and Confluence are tools that seem to have relatively low-friction authoring experiences. (Slab’s the one I’ve used a lot.) 

The authoring experience also encompasses the “maintaining” experience. Let’s say there’s a typo, or something that’s outdated. How much effort does it take for me to correct it? Because if I need to make a pull request or request permission to edit the document, I’m probably not even going to bother. So ideally people feel empowered to make changes from a technical perspective, like editing typos or keeping things relevant. 

There are certain things you wouldn’t want people going in and changing — for example, a team’s on-call expectations — you wouldn’t want someone to go in and make changes without a broader discussion. But in my experience you don’t see people going in and changing those things very often, if ever, because the social expectations are that you wouldn’t make changes without a discussion. 

Then think through the discovery experience. The north star for a good discovery experience, in my opinion, is when employees can find something without interrupting their colleagues. 

For example, in Slab’s federated search, when you search for something it’ll look across GitHub, Slack, Google Docs, or any other places you have documentation stored. It’s like a one-stop-shop for documentation. And the reason having something like that is important is it gives employees the confidence that if there is information on a subject out there, they can reliably find it. 

Inevitably someone will have to nudge their colleague and ask how something works. But the goal is to reduce the number of times that happens. 

A common solution here is to make the navigation or structure of existing documentation better. And to that, I’d say there’s a spectrum of people: there are those who just want to search for keywords and don’t want to go through a hierarchy of folders or tags, and there are those who love keeping things really organized. In my experience, a system that allows for both will drive the most adoption. 

What that means in practice is putting some thought into how things are organized (for example, by team or by use case). And then making sure there’s 1. a categorization or tagging feature as part of the authoring experience and 2. a way to search. 

One other major factor to consider is the administration experience. These are usually privacy-related things to consider, like making sure only current employees have access to docs. Or only certain employees have access to docs that have confidential information. You want to make sure your IT team is on board with how the tool is going to be used to share information. 

Choose a strategy for implementing the process change

Before making any change, keep in mind what the organization’s appetite is for the change. You’re asking people to do something new and possibly unfamiliar, and it might create some pushback. 

A good approach is to figure out where you can start with documentation that’s going to provide the most value. That way we can start small and prove that this is a good investment of time. For that, two strategies come to mind:

‍1. Follow the pain. What is the thing that employees spend the most time on? Maybe it’s that people are interrupting their colleagues to search for things that could be written down. Start there when creating your list of things to document first. 

And it should be natural for team members to talk about time savings. “I used to spend two hours a week answering slack DMs about how stuff worked. Now I don’t spend that time anymore.” 

From there it’s easier to justify further investments in documentation. 

2. Stop the bleeding. “All new documentation needs to follow our new best practices.”

You might have all these legacy systems that have poor documentation. But you’re not going to pause what you’re doing and add all the docs needed in those areas. Instead you’re saying, “we’re going to make sure that anything new coming out from now on follows our best practices for documentation”. 

If you’re able to look at the new systems and recognize that they’re easy to maintain, it’ll be easier to go back and make a dedicated investment to improve the documentation for the legacy systems. 

A combination of those two strategies will help you realize how much time should be invested in documentation and what the next areas to improve are. 

A few other tips for implementing a change to the documentation process: 

• If someone isn’t contributing to docs when they should, it’s probably an alignment problem. This person might not understand what you’re trying to do with documentation.
• Managers, or champions of the process change, should think about the moments where it’s easy to nudge for more documentation. Most teams have a daily standup, for example. When an engineer says they shipped something, someone else can say “is there a doc that I can consult on how it works?” And either they’ll say yes or they’ll go write one. Another example from my experience: I’ve been on teams that did a “demo hour” every other Friday to show off the things people were working on. And a common question was “where can I read more about it?” So these gentle nudges can help get the team into the practice. 
• You can also enforce documentation with things like production-ready checklists. Before you launch a new service, complete a checklist requiring a system diagram or playbook for responding to the top three possible failure modes. 

As a final note: know that there are times when it doesn’t make sense to invest in documentation. An early-stage startup that’s trying to find product-market fit should probably stay focused on shipping product and testing experiments without having to document everything they’re doing. A growth-stage company, on the other hand, is probably focused on improving scalability, reliability, and resilience, so investing in documentation makes a lot of sense.