Creating internal documentation is nobody's favorite job, but no matter how much you dread documenting all the things, it's nearly impossible to function as a business without it. And tossing a few sloppy outlines onto paper or mish-mashing speculative ideas together isn't going to cut it.
Remember: when creating documentation, you're not speaking to people with institutional knowledge. You're speaking either to people who sit outside your team and aren't privy to your department's lingo, or to the newbies who don't yet know their CRMs from their CMSs.
I've seen my share of bad documentation and have created plenty of (I hope!) good documentation. Here, I'll share my tips for creating documentation that stands the test of time—and that people actually use.
1. Don't get bogged down by the details
If your internal docs are so convoluted that you break down every single process and concept within that process in agonizing detail, you and your readers are in for a rough time. (Unless they're speed-reading champion Anne Jones, who can read 4,200 words per minute. In which case, can I get an intro?)
You're also going to have a field day when something inevitably changes and you need to update your docs to match.
Say, for example, your team moves your entire webinar flow over to a new marketing tool to better track attendees and form submissions in one place. Imagine having to go through 120 pages of documentation to find and eradicate any mention of the way you used to manage webinars.
For overarching processes, it's better to whittle down the writing to a digestible format, with enough detail for it to be comprehensible, but not so in-depth that any tiny change in the process would make the whole lot moot.
At Zapier, for example, I help manage our monthly product newsletter, and it helps to outline each step in the process really simply.
That way, if ever I'm out of office, someone else can easily take over for me; or if there's a change in the process, it'll be super quick to update.
Of course, there are times when it pays to be specific—like if you're writing instructions on how to use a specific tool for a specific task. But even then, you need to use your discretion on the level of detail. For example, here's the table of contents for how we teach folks at Zapier to use our content management system.
In our team documentation, we break each topic down into sections so it's easily navigable, but each section is so short and to the point that anyone can learn how to use our CMS. Any abstract information about what we publish and why is kept inside our team charter to avoid confusion.
2. Keep your processes straightforward
We humans have a bad habit of overcomplicating things.
That's why, at Apple, engineers are asked to explain a complex technology or product in really straightforward terms. If they fail to come up with a coherent answer, it's proof they haven't fully understood the concept. A lot of this tendency to overcomplicate is rooted in what's called complexity bias. If we're evaluating two solutions to the same problem, let's say, we tend to favor the more complex option. So when we need to solve a problem, we may shirk the obvious answer.
Take project management, for example. Usually, a project manager's internal docs come with a list of project templates for company use. This is how we kick off projects at Zapier.
Pretty handy, right? All you have to do is make a copy of the template and get to work.
But let's say you're working on a project that involves a number of teams, and you're asked to set up the same templates across four different tools because every team uses a different app. The process itself is too convoluted, so there's no way to document it well.
If the process is complicated, the documentation will be too. If you can't explain something in straightforward terms, you should correct the process until you can. Your processes—and the documents explaining them—should aim for what helps the most people, not what helps a few people the most.
3. Replace jargon with plain language
Let's be real: your fresh hires don't have a clue what's going on.
I certainly didn't when I first joined Zapier. What helped me find my feet were loads of internal docs that were intentionally written with newcomers in mind.
Whether it's training materials, employee handbooks, or standard operating procedures, laying out everything in a non-daunting way can bring new team members up to speed faster. An entry-level team member who's just joined Marketing Ops, for example, isn't necessarily going to know what MAU stands for or what "reviewing critical KPIs in terms of bounce rate" means.
Cognitive psychologist and linguist Steven Pinker describes this phenomenon as "the curse of knowledge." He coined the term to describe what happens when experts overestimate the knowledge level of non-experts. We tend to assume too much knowledge, don't provide enough context, and fail to define abbreviations or jargon we take for granted.
So: assume the reader can easily grasp the concept at hand, but take the time to explain it to them as though they've never heard of it. Like this glossary we use at Zapier.
Newcomers will connect the dots and start making an actual impact on the business faster.
4. Include broader context about each team
Having a strong company culture isn't something you can just declare. It takes deliberate action to bring people together and to make every department accessible.
So: how do clear communications better company culture? For one thing, internal documents are a great way to establish the company in terms of character and style for employees. If employees feel like they're a part of something that they know and understand, they'll perform better.
Take a content strategist, for example. If they know what Marketing Ops is up to, and understand how they go about lead scoring and segmenting users, the strategist will be better equipped to shape the narrative of the story they're telling—because they'll have a better idea of the audience they're serving.
At Zapier, we do this by breaking down our team structure and giving clear instructions on how to work cross-functionally.
Essentially, every company runs more smoothly when different departments can all sing the same tune and collaborate easily. Sharing ideas with people who work outside the department means you can establish meaningful working relationships. This, in turn, leads to greater insights and better business decisions.
