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.

Focus on What You Can Control

It bears repeating: only focus on the things within your control.  Keep an inner scorecard, and don’t let external events sway you.

  • You can’t control the weather, but you can take an umbrella, buy rain boots, wear warm waterproof clothing, or even take a car.
  • You can’t control other teams, but you can keep asking questions and making sure information is shared, expectations are set, give feedback for next time, grease the wheels as much as you can.
  • You can’t control what other people decide to do, but you can influence them by telling them what you want, why it’s the best course of action, why they should help, why they should care.
  • You can control what you work on.  Go find things that YOU care about and do those, fill your time up so full with these things that you don’t have bandwidth for the nonsense other stuff.
  • You can control who you work with.  Go find the people you love to work with and make beautiful useful things with them.  Go play with them and fill your roster up with so many things that there is no room for the complainypants and information silos and hot/cold cats and all talk no action windbags.  And if you can’t find the good people here, just leave.
  • You can control where you work.  If the office is too full of distractions, if your neighbors are loud, if everyone wants a piece of your day, go somewhere else.  Go work in the cozy hidden nook with plenty of sunshine and stuffed animals.  Go find the quiet spots where other people want to do heads down no talking work.  Go into hermit mode and turn off email, phone, IM, everything.  Say no.

At the end of the day, a lot of things are within your control.  You have flexibility to make your environment enjoyable and productive.  You have skills, glowing reviews, vacation days, and a financial cushion.  You have optionality.  If you want to leave, it’s pretty easy to do so.  Just be sure that you’re not going to repeat old mistakes if you leave.

If you stay or if you leave, make a reasoned conscious decision.  If you stay, what are the factors here worth staying for that other teams and companies don’t have?  If you go, what are the factors on the new team, at the new company, that would be different from what they are now?  New is not always better by default.  On the other hand, if you already know something is not working, you shouldn’t bother to keep doing it.  Drop it and pivot to try something else.

Against More Meetings

Something I have noticed about coworkers’ schedules: some of them spend more than 80% of their week in meetings!  If that is actually the case, how can they do their job on 20% of their available time?  Either they know some magic productivity tricks that I don’t (in which case I should ask them to share), their job descriptions are different (possible–managers might rightfully be expected to meet all the time to tell people what to do and get status updates?), or they’ve lost control of their schedule and are merely reacting to work rather than prioritizing and proactively getting the right getting work done.

I am not a productivity guru.  My job description does not include having meetings all the time (although it does include “building relationships with crossfunctional partners” and “influencing without authority to launch crossfunctional projects”).  And I hate the feeling of a day lost (wasted) to unnecessary meetings.

There is a communication problem in big companies.  Facts: there are more people in an organization, problems tend to require solutions implemented in tandem by multiple teams, most organizations have terrible communication systems or no formal ones at all.  All of these lead to a host of productivity and morale slaying poisons, such as: lots of unnecessary meetings, email overload, snails-pace decision-making, snails-pace execution, bureaucracy and red tape, and the appearance of busyness with no results to show for it.

Take one example: manager A volunteers his team for a small project that is not on their priority list for the quarter.  The project could be completely owned and run by 1 person.  Instead, he schedules multiple meetings with the entire team.  The person who is the de facto project lead (and there is always someone who volunteers through their actions) continues this trend of multiple meetings to get “consensus” and “feedback”.

What is wrong with this scenario?

  1. If a team (or even one person) is to be effective, it/he/she must be able to prioritize and focus on completing the most important projects.  Taken to an extreme, if a request comes up that is NOT on your list of most important projects, you must reject it.  Yes, it might be a trivial or small task, but THAT DOESN’T MATTER.  Anything that distracts you from your larger goal, even for a second, is not moving you towards progress on the real drivers of success.  Learn the power of saying NO.  Managers–it is your responsibility to protect your team’s valuable time from distractions.  Minions–it is your responsibility to push back and tell your manager or equivalent that working on this small project means not working on the most important projects, and which is higher priority for them?
  2. Competent managers should be able to scope out projects and only staff the minimum number of people to complete it.  This is especially true if it is not a prioritized project.  If the project only needs 1 person, don’t staff 5 just because you can and it might be nice to hear what others think.  This will only lead to inefficiency and zoning out and frustration.  (The person who is doing all the work feels like the others aren’t pulling their weight, and the others feel like their time is being wasted.)
  3. If you are the de facto lead of a project, or even the formal lead, ask yourself: do you need these other people on the project?  Are there actions you need them to take?  Is there specific feedback you are looking for, and do they have a history of being able to give you that feedback?  If the answer to any of those questions is “no”, for the love of god release them from the project.  Tell them “hey, thank you for offering to help me on this.  I’ve got it for now, but I’ll let you know if I need your help in the future.  I’ll give a heads up to the manager so you can get back to your most important projects.”

The most productive non-managers I’ve ever worked with eschewed meetings, focused on their most important projects, and built time in their schedule for brainstorming and learning and exploration and deep work.  They were domain experts who didn’t let themselves get yanked around by low priority asks from other people.  Instead they allotted a certain amount of time to helping others, pushed back to request that longer projects get prioritized, delegated where possible, and were generally polite but firm.

One of my work-related areas of improvement is to be like this.  Prioritize properly, develop a laser focus on completing the most important projects, and decline or batch meetings like there’s no tomorrow.  Time is to be protected and hoarded like it’s more precious than gold!  Don’t let yourself be distracted and do your best to roundhouse-kick bureaucracy in the face.


For more on anti-bureaucracy/meetings/corporate life and prioritizing your most important projects, see DHH’s entertaining and true rants on the Signal v. Noise blog, and Cal Newport’s Deep Work [public library].