Last updated 23 Jan 2021

Writing effectively in software engineering organizations

My job as an engineering manager requires a lot of reading. Every day, my browser gains a few more tabs as I open internal documents that people share with me in the course of our conversations. In sharing those documents, people are seeking to provide me with more detail, background, and context about a topic we’re discussing. At the end of a day or week, there can be a whole lot of documents competing for my attention.

My job also requires a lot of writing. The written communication that my team and I generate is likewise an implicit request for the attention of future readers. Their attention, like my own, is a finite resource. Information overload is real.

If our communication isn’t crafted with purpose and intention, it places a burden on our audience: they’re left to decide whether the communication is worth their attention, whether it requires their feedback, what the key takeaways are, whether there are hidden action items or implications buried within, and so much more. They have to do work that we could have done for them, and that we’re best positioned to do well.

The culture of communicating via longform writing is strong at Stripe, and that’s led me to think a lot lately about what it means to be good at this. A lot of this is applicable beyond written communication, but written communication skills seem to be an area of … particular opportunity … for software engineers.

Important purposes, essential questions #

My thinking starts with considering the reasons we need to communicate in an engineering organization. Among them:

To influence decisions.
To summarize decisions.
To solicit input and drive alignment.
To articulate tradeoffs.
To share knowledge.
To share accomplishments or setbacks.

How do we effectively achieve these important objectives via written communication? Each of them requires a distinct approach, but they all require asking a few key questions:

Who is the audience for the communication? Are they busy? Are they familiar with the subject matter? Do they need to make or contribute to a decision about the topic? Does the topic impact one of their projects or goals?
What is the purpose of the communication? If we can’t complete the sentence “It’s important that <audience> read this document so that we can <purpose>”, then the document may be for recording purposes (see below), or we may need to refine our own thinking before we share it. (When considering a document’s purpose, the list above is handy, but certainly not exhaustive.)
What do you want readers to take away from this communication? The TL;DR formulation is popular for a reason. The exact framing may vary depending on the purpose of the communication, but an effective document should have a clear summary of some sort near the top.
What can we leave out, or link to elsewhere? The goal of communicating is not to share every fact we know, and all context is not created equal. Focus on the content that is necessary for achieving the communication’s purpose. Use comments or other documents to provide additional, optional context.

Depending on your comfort with the topic you’re writing about, and your comfort with writing itself, it could be hard to tailor your writing based on the answers to these questions, and that’s OK. Sometimes it makes sense to do some stream-of-consciousness writing before you move on to crafting your communication. Put another way: don’t let yourself get blocked by the need to answer these questions up front, but do press yourself to answer them, and refine your work as a result, before you press send.

Writing for the record #

Writing “for the record” is a distinct purpose with different considerations. A document created to record a moment in time — meeting notes, your personal reflections on a topic, or notes from a brainstorming session — can serve as an artifact of the moment. These documents don’t need to be particularly intentional or audience-driven, but that also means they are likely not a useful tool, on their own, for effective communication with others.

Another thing to keep in mind about moment-in-time documents is that their content can rapidly become outdated as teams, projects, and perspectives change. If you’re sharing these types of documents, make sure to prominently include the date when they were created or last known to be accurate.

Documents that intend to brainstorm about a topic are hugely valuable to the group directly involved in the brainstorming, but are very likely require synthesis before sharing with folks who weren’t directly involved. Share these in support of a communication that you write with purpose and intention, but probably not on their own.

Templates, patterns, and prior art #

Effective communication doesn’t have to be (and perhaps shouldn’t be) a creative writing exercise: it’s OK for your approach to be formulaic, for your writing to be dry and direct, and to draw inspiration from (or shamelessly copy) the things you’ve seen that work well.

Templates with predefined section headings and prompts can serve as a starting point for common types of communication, such as project briefs and design documents. For other types of communication, you can learn and lean on simple patterns like the tried-and-true, reader-centric inverted pyramid.

When you’re working on a piece of writing, take the time to review and reflect on examples of the same type of communication written by others. Who were they writing for? How did they organize their thoughts? How much did they write? What questions were you left with when you were done reading? What could they have left out?

A high-leverage activity that gets easier with practice #

Effective written communication is incredibly high-leverage: I’ve benefited countless times from reading a well-crafted document whose author couldn’t have known that I, in particular, would read it someday. I’ve conveyed complex topics to others with the push of a button, ensuring a follow-up synchronous conversation would be focused and informed. A document written with purpose and intention has a surprisingly long useful life, and that same document can scale in a way that in-person conversation cannot. When well-crafted documents are searchable and findable, their value increases even further.

None of this happens without effort, and that effort can feel like a lot if writing is outside of your comfort zone. If you aspire to be a leader who influences others and plays a pivotal role in big decisions, the effort is worth it — and it gets easier with practice. Embrace written communication opportunities when they present themselves, even if it’s a challenge, and create opportunities of your own. A regular practice of writing about the who and what and why of your work will, over time, pay big dividends in your ability to rapidly and effectively communicate with others.