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.
Documentation in and of itself is not an important business outcome. But there’s always a business outcome that improving 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 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:
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:
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.
The north star for a good discovery experience, in my opinion, is when employees can find something without interrupting their colleagues.
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.
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.
Managers, or champions of the process change, should think about the moments where it’s easy to nudge for more documentation.
A few other tips for implementing a change to the documentation process:
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.