Good Engineer, Good Writer
Note: this post is part of a series about growing your engineering career
Have you ever read code and wondered what the author was trying to do?
Have you downloaded a piece of software and spent hours trying to understand how it works?
It happened to me hundreds of times.
Engineers, especially young ones, have a tendency to jump into the implementation, write some code, expect their to pass code review without pushback, deploy it and voilà. This may work when you are the only stakeholder, but it rarely works.
Writing software requires communicating at every step of the development process:
design: explain what you are going to implement and how you will do it
implementation: articulate to your teammates what you did, why you did it, how you did it in a particular way, what may break and how you tested your changes
deployment and operation: document the software, how it works and write actionable runbooks.
The more efficient you are at communicating, the less friction you will have along the development process. For example, if your design is articulated and understood by your teammates, there will be almost no pushback for the code review. If your documentation is thorough and covers all use cases, customers will ask fewer questions and not reach out to support.
I have been transformed by the writing process at Amazon. In fact, my short stint at Amazon had a massive impact on my career, but this is for another post. Each meeting I attended required having a one to three pages (sometimes six, but it was discouraged) document that explains the problem they wanted to discuss, their solution and alternatives. This process forces engineers to articulate the issue being discussed during the meeting. Every meeting attendee had to read the document.
Very often, I found that
I was not tackling the correct problem
I was taking the wrong solution
It was not a issue worth solving.
Limiting the document length (one or three pages) forces engineers to be concise, go to the point and prevents them from boring an audience with useless slides.
My (short) tenure at Amazon and later, my work at Twitter forced me to iterate on my writing style and I came back with the following principles:
be concise: attention span is scarce. If you cannot articulate a complex problem in one to two pages, you may not understand it well enough.
write for your target audience: spare the details your audience may not care about. Make sure they understand it.
answer the basic questions: What? Why? How? When? Explain the context in one or two sentences, the core issue at hand, and then go deeper about how you are solving it.
a picture is worth a thousand words: with a strong French accent, it’s regularly difficult to explain an idea. I found that adding pictures is more efficient than words. Bonus point: you can reuse the same picture in other documents.
Last, writing is not only about the other, it’s also about you. Writing down your thoughts helps you get clarity.