Driving Decisions With Writing

I feel uniquely productive when I write. Sometimes I struggle to express my thoughts verbally but everything becomes clearer when putting pen to paper hands on keyboard. Writing should not be mistaken for delivering, but it is an incredibly useful tool to remove roadblocks or focus work. This post will review some techniques I’ve learned for writing effectively.

Principles

No matter how formal or informal, every document you write should have a purpose and an audience.

We don’t write things for the sake of writing. We write for a reason, whether it be a temporary scratchpad for notes, or a long-form narrative to get an initiatve funded. Understanding the purpose of a document is key to deciding the content and scope. Similarly, someone is meant to read what is being written. This could be the writer themself, or any number of audiences with different backgrounds, skillsets, and perspectives. If you understand your audience well, you can predict how they will digest a document and what questions they may ask.

Example: Last year I wrote a variety of documents for a specific project. Some of them were temporary, tactical documents to align other engineers on a plan. Since these documents are meant to make decisions quickly and everyone reading them had sufficient context on the project, they were usually very concise and require minimal background information. I also wrote a developer guide for how future features need to factor in the data storage requirements imposed by that project. The audience for this was any current engineer on the team plus new hires who have no context at all. When I did an initial review, it was clear that me being too in the weeds on my project meant that I had skipped some important background information when writing the developer guide.

Tactics

What? So what? Now what?: Document writing often boils down to answering these three questions. What is the problem that needs to be solved? Why should the reader care about it in the grand scheme? What is the recommended path forward? Organizing thoughts into this format helps to build a concise message.

Forcing The Issue: A common mistake I see is when engineers find a problem, they identify some possible solutions, and then present that menu of options to a decision maker without providing their own opinion. It’s much easier to get the feedback you’re looking for if you frame something as “I’m going to move forward with X, unless anyone disagrees”. This allows decision makers to quickly give a thumbs up or thumbs down. People often care less about what decision gets made, and more about confirming that all of the options have been weighed appropriately. Not all decisions are that important. It’s often better to pick a decent option quickly and move forward than to pick the absolute best option.

A Picture Is Worth a Thousand Words…But A Demo Is Worth More

Sometimes the best strategy when writing is to not write at all. Consider the graph below that shows a latency regression. It would take several sentences to fully describe what is happening in this graph. Yet without any background information, anyone looking at the image can immediately understand the timing and severity of the latency increase.

Some people struggle to understand a concept when it’s just text on a screen. Or they like the idea but don’t think it’s feasible. Showing them a mockup or a proof of concept can make them much more amenable to an idea. A previous applied science team I was on was met with a lot of friction on our more innovative ideas unless we could back them up with a tangible demo.

Tips

Be Specific: A common mistake I see is people writing vague sentences. For example, if you’re presenting the tradeoffs of a feature and say “latency will increase”, that’s not enough information for a reader to make a decision. By how much will latency increase? 10ms? Will it double? Will it breach the SLA?

Message Discipline: Sometimes to get your point across you need to sound like a broken record. Hit the same point again and again until you wear people down to join your cause.

Omit needless words: Use concise language when writing. Every word should be meaningful.