The Virtues of Documentation

Recently I’ve been transitioning roles across teams.  The easy transitions have happened when the new team has been organized, and when they have good documentation (e.g. process docs, product requirement docs, design docs, training docs, etc.).  When there are no such docs, transitioning is a long and confusing slog bouncing from one person to the next, trying to collect important information but realizing that each person has a slightly different understanding of what the state of affairs is, and that you might be the one responsible for piecing together what the actual source of truth looks like.

So.  Let me extol the virtues of writing documentation!

#1.  Documentation forces you to clarify your thinking, lay out all assumptions, and make sure that everyone is on the same page.

When you write something down, you distill nebulous ideas into concrete form.  You open up for comments.  You share commitments and make sure that everyone shares the same view of the world.  You find out if the definition for a piece of jargon you’ve used for the past 3 months is actually wrong.  You confirm that you and other people on the team are talking about the same thing when you talk about X or Y process.  You check and confirm that every action item committed to has been completed.  You collect all future plans in the same place and make sure everyone understands what they are supposed to do next, and what they are working towards.


#2. Documentation allows you to identify weak points and areas for improvement.

Writing down how something works forces you to understand where things could go wrong.  It makes very clear when there are extra steps, or steps that don’t logically follow from previous ones.  You have the opportunity to track and record historical discussions of why this feature was chosen over this set of available options.  You get the opportunity to think about whether the current way of doing things is the best way.  When describing an existing process to a new team member, you may get more insight on whether legacy systems don’t actually make sense.  When you understand deeply and clearly how something works, you may see parallels in unrelated fields that help you improve your work.


#3.  Documentation is more enduring, shareable, and scalable than human memory.

If you have something written down in a document, you don’t need to spend brain space remembering all of its details.  It doesn’t matter if the project gets stalled for a quarter and then comes back to life the next quarter–you can just refer back to the documentation and know exactly where you left off.  If you have something written down in a document, you don’t need to personally respond to every question about it–just point them to the document.  Similarly, if you need to ramp up a new team member on the subject, you don’t need to spend hours 1:1 with them doing a brain dump of ideas and history, you can just refer them to the documentation and spend 30 minutes for Q&A (which can be made into another document, if you have to ramp up lots of new people).  This saves you a lot of time and mental anguish, and means that you can delegate more effectively.


Just remember to keep your documentation up to date.  Your team and future self will thank you.

Leave a Reply

Your email address will not be published. Required fields are marked *