In product organizations, developers and stakeholders interact with the same product from different sides. Their approaches, backgrounds and priorities are so different that we sometimes need a dedicated person to bridge that gap: that's where the product owner comes in.
Back when I joined Velory, we didn't have any product owners yet. At first, this made it harder for me as a developer to collaborate with the "business side" of the organization. This turned out to be a blessing in disguise, as I had to figure out how to bridge that gap for myself, and I learned new skills along the way.
Today I would like to talk about one aspect of bridging that gap that I found to be both challenging and rewarding: written communication.
Case study: the customer support ticket
Let’s say we got a support ticket from a customer because a product is missing from their store. When communicating with the customer support team, I might write:
The venue 3876 doesn’t have
ProductAvailability records for product 3212 because the Sidekiq job failed. I’ll create the database records and refresh the cache.
There are several problems with this formulation:
- Referring to models by their IDs might be useful for developers, but not so much for stakeholders and customer support who will usually refer to entities by their name. It makes the whole sentence more obscure and less expressive.
- It has programming jargon. The customer support team doesn't care that Sidekiq crashed or that you will "create the database records" and "refresh the cache". They want to know how bad the problem is and when it will be fixed. Anything else is just noise as far as they are concerned.
- However, other developers reading this message might need these details.
This all leads to a non-technical person having to do extra work to extract meaning from that cryptic sentence. Not good.
Compare it to this alternate formulation:
The company Acme Inc (venue ID 3876) doesn’t have access to the iPhone 12 (product ID 3212) right now. I’ll restore the product to their store and will let you know when it’s done (estimated time: 30 min).
For devs reading this: that was caused by the Sidekiq jobs failing last night. I’ll create the
ProductAvailabilityrecords and refresh the cache.
It conveys the same information, in a more expressive way for stakeholders. Developers also get the same information in a separate sentence that other readers can skip as we clearly mentioned that they were not the target audience for it.
Bringing empathy to written communication
The situation above is an example of a larger lesson: know your audience and empathize with it. Know how they like to be talked to and which information they need.
As a rule of thumb, developers need as much information as possible so that they can investigate and explore technical issues. Internal stakeholders are more sensitive to big-picture information but sometimes need to know some technical details to help them navigate a situation. Customers however don't care for technical details, they want to know when and how they can get their work done.
It took some practice, but this is now something that I consider before writing any message in our Slack channels: who is this message for, and what would I want to know if I was in their shoes?
When I first started applying these rules to my communication, it was hard. Every message took longer to type, which seemed like a waste of time, especially on busy days.
However, I noticed that in the long run, this was actually saving time by causing less confusion and back-and-forths throughout the day. One well-crafted message can clear up a situation which would have needed a dozen small messages in 3 different Slack threads.
It gets easier with time, too. After getting comfortable with this way of thinking, it became second nature and doesn't add as much mental load to my day as it used to.