Writing made me a better engineer

Last year, I did one of the best things I could have done: I started writing regularly to become a better software engineer. Not only did I become a better communicator, but it also taught me how to think strategically.

Learning to write

In early 2021, I started writing for myself.

I wrote down problems I was working on, sketched out solutions, and documented what I was learning. I drafted meeting notes, conversations with my manager, and ideas I wanted to share with my team. Putting words to the editor allowed me to shape and manipulate thoughts as discrete entities; before, I was operating on gut instinct and fuzzy mental pictures.

I realized that writing about engineering is hard because good writing requires good thinking.

Now, I was able to write software just fine before! I achieved a lot by following my instinct, experience, and inner sense of order. However, I couldn't easily explain my goal or why I was pursuing it.

Learning to edit

I wrote a lot. I took detailed notes while programming. I recorded thoughts I had while on walks. I scoped out entire projects in one session. But I would often return to a pile of half-baked ramblings the next day. Half of the time, I couldn't remember what I was writing about. I couldn't just write down my ideas and rely on them later.

This taught me I was my primary audience.

I had to edit what I wrote, tighten it, and clean it up. I had to convince my future self that my ideas were sound or at the very least understandable. I added more structure to my project documents. I started naming the patterns I used, describing the pros and cons of specific approaches, and exploring alternatives.

Would an event-driven design work? Would our data lake scale? How much would storage need to grow?

Through writing, I learned to distill my intuitions into coherent concepts. I was able to articulate long-term goals and how to achieve them. I read https://www.amazon.com/Good-Strategy-Bad-Difference-Matters/dp/0307886239 and discovered that this is called "strategy."

Learning strategic thinking

Writing about strategy was even more challenging.

A good strategy needs a clear goal vision, a comprehensive view of opportunities and obstacles, and a solid understanding of the technical landscape. You can leave many things unsaid when only writing code and rudimentary project documents. Nobody reads pull requests, JIRA tickets, incomplete meeting notes, and reasons about the big picture. Even an exhaustive, thorough code review won't expose strategic flaws.

Yet strategy is precisely what needs to be discussed and revised most carefully. Maybe that code doesn't need to be written at all!

A lousy strategy impeccably executed is useless, while a good strategy with a lackluster implementation does wonders.

Communicating strategy

I have always been effective at steering legacy codebases towards impactful business goals. But I could never explain how I did it, not to myself, not to stakeholders, not to teammates. This meant that reviewing strategy was impossible.

Instead, we had meandering whiteboard sessions and slack threads; architecture and implementation efforts were pulling in different directions; a lot of glue code was required.

Once I started to focus on writing, things fell into place. After a few months of practice, I wrote a concise three-page strategy document outlining our data engineering strategy. A few critical sentences laid out how to align incoming requirements with long-term goals, acting as a lighthouse for more detailed work.

I started writing similarly short RFCs (see https://dev.to/wesen/quick-tip-tuesday-writing-rfcs-for-fun-and-profit-3bo). I had to persevere for months, writing dozens of documents before the process was adopted for all new development.

Writing for better engineering

Today, I use writing for every engineering task I work on. It allows me to think clearly over long periods. It allows me to make and document decisions and give them the depth and long-term vision they deserve.

(Cover: Battle of Borodino - Baron Lejeune - Wikimedia)