On communicating through writing
In February 2024, I joined a new organization as a “principal engineer”. This was a bit of an adventure — the last 12 months have been an opportunity for me to learn an enormous amount, as well to join a high profile project, sort through a number of substantial project challenges and establish relationships at different levels through this new company.
Whenever joining a new company, I’m always surprised at how different that company works. In this particular case, I rejoined a series of colleagues I’d worked with in the past, but in vastly different roles and with a very different customer base. It was a good opportunity to see both the culture that exists between my former colleagues and I, and the culture that exists in the broader group.
One of the principles that I take for granted is the use of documents as a vehicle for coordinating decisions. I am used to product, portfolio, technical, organizational and managerial decisions all having an accompanying (hopefully short) paper. This exists in pockets in the new company I work for, but it is by no means “common”. So! This article exists to try and explain why I am so used to using documents to drive a shared understanding, and ultimately, a clear decision.
The Fundamental Challenge: Developing an Idea
The goal of most communications is first to develop a shared understanding of an idea. Whether that’s “We should use Go as our primary software development language”, “This application programming interface needs an additional field which determines whether or not this application is a frontend application” or “We need a new team to build a load testing capability”. The second is to allow others to contribute to that idea, bringing their own knowledge and perspective to improve the assumptions that the idea makes or bring a new iteration of an idea that solves the underlying problem. Lastly, there should be enough clarity that a leader can make a clear decision that is well understood in the team.
There are different ways to “develop an idea”. The most frequent ones I come across are:
A “workshop”, in which team members share their understanding in a “brainstorm” against a common model (e.g. on a whiteboard).
A “document”, in which someone takes the time to write up their understanding
My experience so far is that a “workshop” is incredibly useful to gain a lot of perspectives quickly and settle on the “broad definition” of an idea. However, workshops usually do not provide enough clarity that a decision can be made “in the moment” — while participants may feel they share a good understanding of each other's perspective, frequently I find that when it is written into a document and re-read, what’s there is quite different than the expectations that each participant had out of the workshop.
Additionally, workshops miss at least two key opportunities for input. These are:
Inspiration. The proverbial “shower thought” or key moment of insight that happens outside a workshop, when your brain is just idling over the day.
Research. A structured analysis of what other people have done, and been kind enough to communicate in the past.
Feedback. Asking a broader group of participants outside the initial workshop for their input.
Experimentation. Having a go in a cheap way, before settling on a larger investment.
All of these can substantially improve the initially described, rough idea.
💼 Practical Experience: Earlier this year, I joined a very large, company wide project. This project used workshops early on in its delivery to make key decisions, but only some of the decisions were extensively written up. Later, it turned out many of the initial assumptions didn’t pan out, and the project ran into substantial trouble. The project did not have clearly defined checkpoints or moments to course correct. It was put back on track by making clear, key decisions and aligning with senior stakeholders on the new requirements — the majority in time, in writing, and with substantial earlier preparation.
Communicating an idea
Let’s assume that an idea was clearly defined, if not articulated, in someone's mind. There are different ways to convey that idea, each that can solve a different problem. These include:
Verbally
Verbally communicating an idea is extremely cheap, requiring almost no preparation and providing the opportunity for the communication partner to take a directed path toward understanding by asking questions.
Unfortunately, verbal communication scales very poorly. While it is possible to communicate verbally to a large number of people, this substantially increases preparation cost and decreases the opportunity to ask questions with larger audiences. Additionally, verbal communication happens at a point in time, which means if someone is not present at that point, they miss it.
Lastly, while it can be very fun watching a compelling speaker speak passionately about their idea, that passion can bias us toward endorsing a fundamentally weak idea from a fundamentally strong speaker.
With Slides
It is possible to overcome some of the challenges speaking verbally by providing visual aids. This enriches the communication with additional context that can help reinforce the speaker's meaning, and provides some level of retrospect ability to the content later.
This is very useful to communicate pre-aligned ideas, but is less useful for developing them further. It also suffers from the “point in time” problem.
💼 Practical Experience: In October 2022, I and a colleague (Salome Santos) spoke on the topic of how our reliability culture and practice evolved over time. While the talk seemed to be well received, it was the product of 100 hours of work getting the talk written up as a script, making slides and practicing multiple times before delivery. Writing was at the core of the slide delivery.
With Video
It is even further possible to create engaging material by using a recorded talk, and then using video editing tools to provide more complex visual aids for the speaker. Speaker awkwardness can be removed, such as long pauses or other linguistic challenges.
It additionally addresses the “point in time” problem that slides suffer from, but is still not very useful for developing an idea.
💼 Practical Experience: In 2023, I created a course called “practical introduction to observability”. Similarly to the slides, it used writing as the core mechanism to align content. However, to turn writing into video was about 80x the initial writing time. This is a key reason why the content has not evolved quickly, and why I have not produced additional material.
In Writing
Easily my favourite way of communicating. Communicating in writing is substantially more expensive for the author, needing both to articulate their understanding and then to review it before it is published to others.
However, it is far cheaper for the readers. People can frequently read much faster than they can listen to a speaker or watch a video. While text doesn’t inherently provide visual aids, it is possible to enrich it with diagrams (or even videos) to provide the required understanding.
Writing also does not suffer the “point in time” problem, as writing can be read at any point in time — whether immediately after it has been written, or months later as a given idea is being reviewed for its efficacy. It can help us “shift back” in time to understanding our thinking at that point, rather than us trying to imagine it with the biases that our more recent experiences have created.
Lastly, writing is extremely cheap to iterate on. A typical flow for a document might be:
Write the first draft, put it away. Read it in the morning. Edit it some more.
Send it to a colleague for their review. Edit it some more.
Send it to an immediate manager for review, in conjunction with experts from a small community. Edit it some more.
Send it to a broader community for review. Edit, and “publish” it — indicating there will be no more edits, and the decision is made.
This is something that no other communication medium can deliver on.
💼 Practical Experience: This article has been sitting in my inbox for about 4 weeks before I finally took the time to write it up. In the meantime, I added notes on what I wanted to say as I thought of it during my commute, or in discussions with those around me.
Point in time reading
While it is possible for people to read documents at any time, it is frequently the case that people do not prioritize reading material without dedicating time to it specifically. To overcome this challenge, we can employ a “silent meeting”.
A silent meeting is a meeting in which all participants are given the document, and a reasonable amount of reading time (usually 50% of the meeting time). They can then read through the document, raising feedback through that meeting.
At the end of this silent reading period, a moderator will go through the comments in the document, selecting those that seem especially useful for further discussion. The group will discuss each document, after which a note will be made and the author will (later) refine the document based on the group's feedback.
This works extremely well for technical design documents, product discussions or other substantial engineering decisions. Learn more at “running an effective meeting”.
💼 Practical Experience: As part of a project this year, I needed to align with multiple senior stakeholders on how to collaborate and determine a path forward. To do that, I wrote up the current challenges, contributing factors and recommendations and held a “silent meeting”. While there was discussion at the end of the meeting, this conversation anchored all future collaboration, and provided both parties with a clear path forward.
Writing Tips
Communicating via writing is a skill that, like all others, takes practice. This blog is my attempt both at communicating ideas, and improving my ability to do so! However, there are some practical things you can do to improve your writing quickly:
Write toward a target audience. Have a specific group in mind when writing, and review your writing against whether those people will understand it.
Keep your documents concise. While it is useful to “think” in long form, it is awkward to read. The less fluff in a document, the better. As a rule, a document should never exceed 6 pages, and a decision never more than 1.
Remove complexity. When writing, it is possible to repeat yourself multiple times, to use language that is bespoke (or “unusual”). Try and remove as much of this as possible, leaving only the simplified essence behind.
Bonus: Large Language Models
This past year (2024), large language models such as ChatGPT or Gemini have become substantially more prominent. These models excel at digging through an abundance of documentation for fairly vaguely articulated ideas. Ideas written up can be surfaced by these tools, giving readers that “directed path” through the material.
Additionally, large language models can be very useful as editors. This document was edited based on feedback from prompts such as:
Consider this document as a reader who has a professional background, but is earlier in their career. Would you find it interesting? Why or why not? What would make it more interesting?
Consider this document as a reader. What information in it is redundant or repeated? What can be safely removed without hurting the "core message"?
Consider this document as a graduate level reader. What language or terminology is unclear? How could that language be simplified?
That’s it. Happy monday fam!