007. Documentation Is How You Scale
In the last letter, we covered the importance of becoming less necessary so that your team requires less of your time and effort to accelerate productivity. This letter covers how to do that in a sustainable and beneficial way. It may just be the most important chapter of all.
Most leaders understand the importance of documenting knowledge and processes, but too often de-prioritize writing things down in favor of writing more code. This is a short-sighted and misguided approach. It consistently results in large tech debt, poor knowledge transfer, and the team's reliance on one person to have all the answers (usually you).
That said, simply writing down more things isn't the answer either. It's important to know what to write down, who to write it for, and perhaps most importantly, where to put it. The good news is, as long as you remain consistent, these habits are quick to instill in a team and instantly beneficial to everyone — especially new hires.
Better, consistent documentation for my teams meant less time spent hunting for information and more time spent producing — which made for both happier developers and development leaders alike.
Let's see how.
What to Write Down
Your team makes decisions and solidifies processes all day long. Ensure this information doesn't get lost in the ephemera of last month's Slack chats and Zoom calls.
Processes
If you need to do anything more than twice, write down how to do it.
You need not create an essay for a three-step process. Use bullet points or numbered steps, with a sentence or two of context. Imagine that you've taken the day off and that someone without the knowledge you have in your head needs to find these instructions and execute this process. Not only will this be beneficial if you do actually happen to be out of office one day, but you yourself will likely benefit from the step-by-step reminder, especially after returning from a vacation.
For complex processes or technical documentation, provide more context. Start with the big picture, e.g., "This document describes how to deploy a new version." What's obvious to you may not be so clear to other team members and new hires.
When describing each step, more than simply writing down the terminal command to run, leave a few sentences describing what it's supposed to do and what other pieces it affects. Based just on what you've written, someone else on the team who's new to the process should be able to start troubleshooting it.
Decisions
Slack is not documentation. When looking for a decision that was made last month, don't subject yourself to keyword-searching dozens of irrelevant threads and messages. When decisions are made, make them easy to reference again by writing them down somewhere more permanent (more on that below).
Not only will this make information easier to find, but it solidifies shared team knowledge for anyone who was out on leave or who happened to miss the conversation or meeting. Giving your team one place to reference important decisions ensures everyone is on the same page.
Who to Write It For
Make no assumptions about your reader. Everyone on your team has knowledge and expertise — but not the same knowledge and expertise as everyone else.
Every piece of documentation you or your team creates should be written as if it was going to be relied upon by a brand new hire — because it will be. For example, while you don't need to go so far as to explain coding fundamentals in your style document, note and link to references for any particular code styles and linting tools your team uses. When creating a README for an internal repository, write it with the same diligence as you would if it were a public repository.
If you're unsure whether something has a sufficient level of detail — test it out! Have a team member who's unfamiliar with the subject read it over and ask any questions they may still have. If those questions seem pertinent, fill in the blanks in your documentation.
Where to Put It
There are a myriad of tools your team uses to communicate. For this question, the answer is highly personal to how your team works — but there's only one right answer.
Put documentation where your team will read it.
A strategy that has worked well for my teams in the past is to keep documentation as close as possible to its subject. Product documentation and technical guides live in the code repository. Team-related docs live next to where the team makes plans, such as in Notion, Confluence, or Basecamp; these include process documentation, notes on code style and tooling, and onboarding checklists for new hires.
Enlist Your Team
As a leader, it's your responsibility to champion the creation and upkeep of documentation. That doesn't mean you write it all yourself.
Make a point of asking for docs whenever team members introduce new code or propose a great new idea. Ensure you ask for docs to be updated when changes are made to the codebase or processes. Whenever your team or other leaders make decisions, say, "This sounds great! Let's make sure to document this in Notion so we can act on it as a team."
Review documentation with the same diligence as code — they're both executable instructions, after all.
Remaining consistent with your team helps instill the habit in everyone.
Take it to work today:
Write documentation for processes and decisions such that a new team member can understand and act on them. If it’s not documented, it doesn’t exist.
Put documentation where your team will read it. Keep docs close to the relevant work.
Instill the habit of creating and updating useful documentation in your team. Lead by example.
Great write-up as always!