I like to write.
Well, I like to have written. And I especially like when people read what I’ve written, and find it useful. It brings me joy.
Writing useful things also helps me do my job. When you’re growing a team, you only get so far on oral tradition, habits, and institutional memory. When folks need to bug a senior team member to access your most valuable knowledge, it’s harder to level people up.
Given that, I’ve been spending more and more work time on docs. I’ve written docs about project management, client communication, hiring, architecture, 1:1s, product development, and dozens of other topics. It’s been really valuable for helping clarify our approaches to certain things. Concise, readable docs can give folks a big leg up.
However, I recently started to notice a problem.
I would gather input from our team on a topic, draft a doc on it, we’d iterate and refine it, and yay it’s great. But beyond that, it wouldn’t get referenced. Creating the doc would help us learn and refine our thoughts, but its value would too often stop there. A team would be waist deep in some tricky problem, and eventually I’d realize, “Wait. Isn’t this a problem we wrote about in our Project Management at Steamclock doc?” And we’d all sort of nod in vague recollection, not quite sure why none of us have have referred to that clearly written doc from a year or two back.
And if a doc isn’t being referred to, it’s not doing any good.
We already do a lot of things to help ensure our docs are useful: we make them short and sweet, well maintained, consistently formatted, and for the most part they’re on topics we’ve agreed are important. We work to organize them in an easy to navigate hierarchy in our Coda (think Notion but with more powerful automation and a bit rougher around the edges). So why was nobody referring to some of them?
The power of guides
My latest level-up on this came via Adam Avenir, who has led companies and teams for ages. He explained that the docs he’d written that were most often referred to had a theme: they were how-tos or checklists. Guides on how to get a thing done.
This struck me as powerful. Obvious in retrospect, as many powerful ideas are.
If a doc is clearly a guide for doing a certain thing, then people are a lot more likely to think of that doc when they’re doing that thing.
A team of individual contributors might be aware of “Project Management at Steamclock” existing, but are unlikely to prioritize re-reading it when a certain project management topic comes up. On the other hand, docs like “How to Prioritize Issues”, “Making Tough Decisions”, or “Run a Design Sprint” draw you in at the right time – the title tells you when the doc is useful!
Thoughtbot’s Playbook is mostly organized this way – you can sort of drill into it with a certain task in mind, and many of the docs are titled in a way that indicates what they’re meant to facilitate. And for the ones that aren’t titled that way, well – I’d wager that their page “Facilitating usability tests” gets more hits than the generically titled “User Experience Design” primer.
With this in mind, I’ve recently retitled and refined many of our docs to act more like how-tos and less like topic overviews. A couple months in, it’s already paying dividends. Not only is the team more inclined to navigate and refer to these guides, but they’re easier to write!
Mind you, a guide doesn’t need to be too prescriptive or constraining. You don’t want to bog down a thoughtful and creative team with a ton of policies that tell them what not to do. You do want to equip them with useful guides outlining how we typically do specific things, especially if those lessons were hard won.
And yes, from time to time it’s worth writing a primer, overview, or a thoughtful exploration on some key aspect of the business. In practice though, the docs your team will reach for most are the how-tos. Guides that help them do something.
In order to help encourage this style of doc, without discouraging less formal notes and docs, we now distinguish between a Guide and a Note in our doc “How to Start a Guide”:
- Guides are nice docs we’re maintaining with the goal of them being concise and correct. This is most often worthwhile for “how to” docs that will be referred to more often than they change.
- Notes can take any other form, and are great for capturing knowledge from a specific point in time: meeting minutes, findings from research, results of a brainstorm, a project update, etc. These are generally docs “as of $date”
Growing a team is all about iteratively putting yourself out of a job. You teach people how to do what you do, so you can go and do the next layer up of broader, trickier, or more uncertain work.
Sometimes all you need to do is write out how to do something, so talented folks can pick it up and do it – then do it better.