Why Write? (Original Draft)

Many engineers discount the value of writing. Why waste time crafting paragraphs that could be spent shipping code? In contrast, I credit it as the single most important skill of my career.

For some, the thought of writing evokes an idea of a polished technical artifact created through weeks of reviews with senior leaders. That’s certainly a common and particularly visible variety of it. It’s far from the only way to write though. Writing can be a messy, quick, personal process as much as a thorough peer-reviewed exercise in rigor.

An important shift in my relationship to writing was to consider it as a tool to clarify my own thinking, a narrative equivalent of rubber duck debugging. This reduces the pressure to craft something perfect on which others might judge my language and logic abilities, and instead shifts the focus to a more practical problem solving mindset. The purpose of an engineering document is to solve a problem. Sometimes that problem is simply a technical challenge you need to think through independently, or you’re out of ideas and need another set of eyes. Sometimes the technical issues are more easily solved and the real issue is in driving alignment towards that solution. A more subtle problem is when the immediate work flows smoothly but the context around that solution is lost over time, making it harder to onboard new engineers or be recognized for your contributions during promo/perf review.

A document can serve multiple purposes over time. For example, at a previous company I was faced with a decision of which approach to take in solving a core technical challenge for my organization. I started with a simple one-pager outlining the available options, making sure I understood how they compared on the key aspects we cared about. There was a clear winner but I wanted to validate that conclusion given the difficulty of reversing the decision, so I reviewed it with other engineers I trusted with the explicit instruction to look for gaps in my reasoning. One of them suggested another option I wasn’t aware of that turned out to have better tradeoffs than my original pick. That option was unfamiliar to most of the organization, so the document then became a focal point to drive awareness and confidence in this new approach. Later, engineers building the system referred to the document for their implementation decisions. Years later the document was a fixture of the organization’s knowledge base in onboarding new engineers. In that time it was featured prominently in my promo packet and the experience was referenced frequently when interviewing for my next role.

Not every document needs to serve every purpose; many problems aren’t important enough to warrant that investment. It’s incredibly difficult to write a good document in retrospect though, so getting in the habit of writing early and often will create more opportunities to use those documents in a variety of ways.

Maybe you’re working on a smaller feature with a straightforward implementation: why would you take extra time to write down what you’re going to do before actually doing it? If you truly won’t get anything out of the writing process, don’t do it. But remember that coming to the right technical decision is only one problem documents can solve. Is this information the rest of the team would need to know in the future? Will it be difficult to convince stakeholders to support this work? Is this particularly critical work that might benefit from additional review in case you missed something? Would you benefit from being able to communicate the scope and impact of this work in promo/perf/interviewing?

Ask yourself:

• Do I understand what I’m building?
• Am I confident this is the best approach?
• Will stakeholders agree about how to solve this problem?
• How important is it for the rest of the team to know this?
• Would I benefit from documenting the scope and impact of this work?

If you can confidently address these questions without a document, don’t write one. Keep in mind that it can be easy to conflate discomfort around the process of writing with a judgement that it’s not useful. If writing isn’t a familiar tool for you then you will have an inherent bias against using it, so sometimes it’s worth writing a document just for the sake of improving your writing.