10 reasons why you have to exceed at documenting

Jan Schenk

May 9, 2023

I’m leading Postman’s Open Technologies Program Office—our open source program office (OSPO). My team consists mainly of open source contributors, and our parent org, Postman Open Technologies, is an incubator for API tech and a strategy think tank. There’s a bunch of high-profile industry experts that I work with and for, and I’m constantly switching between impostor syndrome and delusions of grandeur to change the world.

At a recent Postman Open Technologies team meeting, I gave a very general direction in saying that we have to be the team that is known for documentation and that we need to document everything individually as well as in a team effort. While there was more context, like our collaboration with the product teams, it is also a general recommendation that I give to myself as well as others in our industry—especially in these fields of work: engineering, OSPOs, and developer relations.

But first, let’s define the term “documentation.” In the context of this blog post, documentation includes external as well as internal technical documentation, blogging, sharing knowledge on social networks, demos, how-to articles, instructions, conference sessions, webinars, podcasts, wikis, infographics, flow charts, and the like.

I understand how easy it is to get lost in responsibilities in today’s fast-paced world. But while you won’t be immediately rewarded for writing documentation like you are for writing code, setting up a process, or resolving an issue, creating good documentation is about showing compassion to those around you as well as your future self. Its impact is mid- and long term, but needs prioritization now.

My top 10 reasons why being great at documentation is key to success

You should be known as the person who exceeds at documenting because:

1. Documenting makes you a better coworker and collaborator. Creating good documentation reduces frustration, lowers the level of collaboration anxiety, and makes previous decisions more understandable.
2. Documenting increases your value. It increases your value as a professional and makes you less expendable. Letting go of a person or a team that built a good part of the internal knowledge hurts. Hiring someone who is known for building persisting knowledge is easier to justify.
3. Documenting helps build your personal brand. Coming across the same author name over and over again when doing research makes you a subject expert. Add on top a few more measures,—like community engagement, mentoring, public speaking, whatever you choose—will greatly help your brand.
4. Documenting builds internal visibility. Being able to refer to something that you’ve written is easier than vaguely repeating what you have said or commented on a team meeting. Colleagues are more likely to give credit if it’s easy to do.
5. You can slice and dice into content creation. Once you’ve started documenting things, you can slice and dice it for content creation. Producing a video, writing a podcast narrative, preparing a talk, or inviting people with similar or differing opinions to a panel is way easier than starting from scratch. It also helps you find a red thread for your storytelling, which is another item on this list.
6. Documenting helps internalize your knowledge. And identify caveats. Repetition, that’s how the human brain works. Writing something down is exactly this. When your fingers are slower at typing than your brain is at processing information, you’re forcing it to repeat the same thing over and over again. That helps you either internalize findings or helps you find catches and bugs in your thinking.
7. Documenting makes your knowledge persist. The most obvious one, but also the most ignored point on my list. Have you ever come across a written piece and thought, Hey, that’s good knowledge, I’m glad someone else wrote it down! only to realize it was you two years ago? We forget, and that’s even part of our learning process. Storing information is not only something you do for others but also for yourself. And even if you don’t regularly update your content, it will be useful for a certain amount of time and maybe even beyond. (Disclaimer: This is not a good excuse for not keeping your documentation up to date!)
8. Documenting saves time. Were you assuming the opposite, that writing documentation eats up a lot of time? Have you ever felt like repeating yourself? That’s probably because you did. When you write documentation it saves you from the tedious work of repeatedly explaining to others. When you’re spending the third time explaining something, your time would have been better spent writing it down. You could still have that discussion with your peer, but you’d have it on a different level.
9. Documenting helps avoid the awkwardness of having to ask. It’s not only you feeling bored about explaining the same old thing a third time this week. It’s also them feeling bad about wasting your time. Coworkers might hold back from asking you because they feel your time is too precious. This hinders collaboration.
10. Documenting makes you better at storytelling. The bigger picture is something that you will be asked for. Being able to not only provide facts and figures but also develop a narrative and make the numbers stick to someone’s mind is priceless.

It’s important to note that while I say “good documentation,” I don’t ask for “excellent” or “outstanding.” That’s not because I think that nothing will ever be perfect; it’s because documentation doesn’t always have to be pristine. Often enough, “average documentation” does the job and is a legit compromise between effort and benefit.

Whenever you consider prioritizing documentation, which includes internal as well as external content creation, you definitely should always answer: “Yes, I will.”