Why Write?

12 Jun 2026

Many engineers discount the value of writing. Why waste time crafting paragraphs that could be spent shipping code?

Because documents are a tool to solve problems.

Solving Problems

An important change 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 and shifts the focus to a more practical problem solving mindset.

Sometimes the problem is simply a technical challenge you need to think through independently. Maybe you’re out of ideas and need another set of eyes, or the technical issues are trivial and the real problem is in driving alignment.

One Document, Many Purposes

At a previous company I was faced with a choice between approaches to a core technical challenge. 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. In this case writing solved my problem of understanding the solution space.

There was a clear winner in the solution comparison, but solving this problem correctly was critical. I asked other engineers to review the document with the explicit instruction to look for gaps in my reasoning. One of them suggested another option I’d never heard of, and it turned out to have better tradeoffs. My attempt at writing to understand the solution space had turned into a way to validate my findings.

The chosen option was unfamiliar to most of the organization, so I worked with domain experts to explain technical details and address concerns. It was a contentious choice, so the document evolved into a persuasive tool to drive awareness and confidence in the approach.

As we shifted into execution, engineers building the system referred to the document for their implementation decisions. It became a repository not just for the decisions made but also the rationale behind them. The document was no longer a way for me to make decisions but a way for the team to execute them.

Years later the same document was a fixture of the organization’s knowledge base in onboarding new engineers. The original technical problem was long solved and the document was now a way to maintain institutional knowledge.

The document was featured prominently in my next promo packet and the whole experience was a focal point when interviewing for my next role. That one-pager had gone on to solve problems that didn’t even exist when it was created.

The Case Against

Ok I can admit writing is useful sometimes. But I’m working on a small feature with a straightforward implementation: why would I take extra time to write down what I’m about 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.

Not every document needs to serve many purposes over multiple years; most problems aren’t important enough to warrant that investment. There is an imbalance here though: shelving an unused document only costs the time spent making it, but not creating it in the first place can have unforeseen costs down the road.

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. But you might be surprised where a simple one-pager can take you years later.