The Value of Writing It Down

Something I don’t think I’ve put enough importance on so far in my career is writing things down. Until recently I only ever wrote down a couple of categories of things:

  • repo documentation in
  • root cause analysis findings after service outages
  • technical design documents for planning new systems
  • process-related agreements like SCRUM guidelines
  • “definition of done” for engineering quality standards

Recently I’ve discovered that’s there’s also value in writing down whatever I happen to be learning.

It actually started with this blog, which I started in order to “get some capital” out of my weekly work for The Man. My thought was that I’m spending 40 hours a week of my time for my employer and all I get out of it is experience and a paycheck. I don’t get any “capital” that I can use in my career outside the company. But by taking some time each Friday to blog about something I learned, I get the “capital” of a document that stays with me even when my current tenure is over.

What I found, though, is that I am doing better at internalizing the experiences that I write up in this blog than I am at internalizing the other things I learn during the week that I choose not to blog about. I guess that doing a write-up of something I learned is, in a way, “teaching” it to others - even if no one is actually reading and it’s just an imaginary audience.

The same thing holds true for writing up internal documents that don’t make it to this blog (either because it’s proprietary information or just not generic enough for a personal blog.) I internalize the lesson better when I write up a quick Quip document and post it on the appropriate Slack channel at work.

There’s a less selfish advantage, too: more people have a chance to draft off your experience. Giving demos at a COP meeting to share what you’ve learned is fine, but only the people who have time to go to the meeting can benefit from it. If you write up what you learned in a document, then anyone now or in the future can stumble across it and learn from your mistakes / struggles / research.

I suppose career advancement is another advantage: part of being a senior engineer is helping other people engineer better and work faster. To the extent that you are doing that in a highly visible way, that’s great material for promotions and bonuses. And the practice at technical communication helps, too.

Self-interest that aids others… Adam Smith would be very pleased.