Optimizing Engineering Communication for Better Developer Experience

‍

Welcome to the third part of the OpsLevel DevEx Series! In our first post, we talked about how the aim of great developer experience is to make it easy for developers to achieve and maintain flow state. We followed that with a second post on how tooling impacts the developer experience. In this part of our series, we’re touching on communication and how teams can optimize their communication to improve that flow state.

The DevEx Series

This blog is part of a series of blogs on developer experience, you can view the index so far here

TL;DR

In this article, we’ll be covering: 

Three types of engineering communication

1. Work as a form of communication --> Most conducive to flow state
2. Asynchronous communication
3. Synchronous communication --> Least conducive to flow state

Communication starts with the communicator

• The communicator is responsible for communicating effectively, either by writing, speaking, diagraming, messaging, or designing tools that clearly convey intent.
• Communication should enable developers to get in and maintain flow state.

1. Work as a form of communication

The most effective form of communication is making your work speak for itself. Work means the following (in order of importance):

1. A design that is intuitive and easy to use.
2. The clarity of your code. 
3. The packaging of the work.
4. Documentation that’s contextual and easy to read.
5. Supporting tools and templates that make discovering, understanding, and using your work easier. (This can be supported by an internal developer portal.)

2. Asynchronous communication

Asynchronous communication minimizes interruptions and facilitates flow state. Some of the channels that facilitate this form of communication include the following: 

• Slack is a chat app with productivity features added on top. Teams should spend the time setting it up properly to facilitate asynchronous work and improve flow.
• Project management software keeps the focus on the project and is designed to be asynchronous. This is potentially better for flow state.
• Email works well for formal, structured communication, legal documents or company announcements.
• Internal wikis are great for organizing company information internally for indexing and searching.
• Developer portals act as a central source of truth for the state of your services, who owns them, and all their related resources.
• Company updates should be shared once a week in a way that developers can consume them at their own pace.

3. Synchronous communication

Synchronous communication is appropriate for planning, emergency responses, socializing, and discussing complex topics that all participants are familiar with. As you set up meetings, consider the following: 

• Meetings are a last resort. Favor asynchronous communication first.
• All participants must take an active part in a meeting.
• Participants must be familiar with the agenda and topic being discussed.
• Continuous urgent work or emergencies tell a story of bad planning or too much technical debt. In these instances, fix the underlying problem causing them rather than having another meeting. 

Read on for the details.

Three types of engineering communication

This article will classify engineering communication largely into three categories (in order of importance):

1. Work as a form of communication --> Most conducive to flow state
2. Asynchronous communication
3. Synchronous communication --> Least conducive to flow state

Depending on the size and shape of your organization these types of communications will become more or less relevant to you. For example, for large organizations it is absolutely imperative that your work speaks for itself and that asynchronous communication is favored to mitigate the number of links and conversations happening at once. This must be used in combination with well established team topologies (Stream aligned teams, platform teams, etc)

If your company is very small (five engineers or so) and everyone knows each other's work, then synchronous and asychronous communication may be more relevant to you, in this particular case experimentation is more important and spending time in packaging work for other teams may not be as relevant, yet (But still important!)

It's also worth noting here that both asynchronous and synchronous communication are important to aid flow state, especially in phases where close collaboration and design are happening, independent of how large the company is. Ultimately we communicate in this way to ensure we design solutions that make flow state easier, and therefore design work that speaks for itself, so types two and three are there to help with type one as well.

Over the next few sections we will explain these types of communication and how to do them effectively to help flow state.

Note: Communication starts with the communicator

When it comes to communicating anything, the communicator should take on most of the responsibility of ensuring that the messaging or the work is clearly understood. In fact, it’s unfair and counterproductive to put the burden of understanding on the receiver. 

At the end of the day, communication should facilitate flow state for developers, and having to spend time deciphering something can drastically interrupt flow state. Instead, communicators should use the tools available to them — whether that’s written language, diagrams, APIs, or automated features — to make things as intuitive as possible for the receiver. 

But what does this actually mean? And how can you ensure that your team’s communication practices facilitate optimal flow state? It starts with contextualizing all work as a form of communication.

1. Work as a form of communication

In the context of engineering, the most effective form of communication is having your work speak for itself. By work, we mean the following (in order of importance):

1. The design of the tool, application, API, etc. Everything should be intuitive and easy to use.
2. The clarity of your code: well-written, structured, contextual comments, etc. 
3. How well packaged your work is. For example, your files should be structured in a way that’s intuitive to navigate. Your application should be properly containerized and/or have a reliable way to install it easily (Nix, Brew, Apt, etc.) 
4. Documentation that’s contextual and easy to read.
5. Curated tools and templates that make discovering, understanding, and using your work easier. For example, by using an internal developer portal.

The order here is important. If your application is not well designed, documenting it will be much more tedious. Plus, your users will have to do more work reading that documentation to understand your tool, which effectively hurts their flow. 

In other words, if you want to enable and maintain your colleagues’ flow state, the best way to do it is by creating work that’s easy for them to understand and use. They should be able to grasp the usage and intent of the tool as quickly as possible so they can apply it to their own work.

This form of communication is important within a team, and it is paramount when it comes to inter-team communication. If two separate teams need to constantly communicate via meetings, Slack, or email to get their work done, that could be a sign that the work (as outlined above) is not speaking for itself. This is brilliantly put in the book Team Topologies by Matthew Skelton and Manuel Pais:

“If, logically, two teams shouldn’t need to communicate based on the software architecture design, then something must be wrong if the teams are communicating. Is the API not good enough? Is the platform not suitable? Is a component missing? If we can achieve low-bandwidth communication—or even zero-bandwidth communication—between teams and still build and release software in a safe, effective, rapid way, then we should.”

It’s therefore important that we see the quality and user experience of the tools we create as gauges for communication. Done right, these elements can help our colleagues easily achieve flow state.

In a similar vein, having a great tool or self-service automation function can be the best way to abstract expertise that others can engage with and learn from easily. This way, team members can access the key points and information they need without having to learn a whole new discipline.

2. Asynchronous communication

In any engineering team, communication tends to happen either asynchronously or synchronously. Let’s explore each of these in the context of the developer experience. 

Due to the nature of the job, many engineers require long periods of uninterrupted time to get work done. As such, asynchronous communication should always be favored over synchronous communication, with meetings only used as a last resort. As 37Signals puts it: “Real-time sometimes, asynchronous most of the time.”

Many of today’s workplace tools are designed to facilitate asynchronous communication, with each one fulfilling a specific function.

Work Chat Apps (Slack)

Most of the communication happening at tech companies today happens over chat, especially Slack. A work chat application is not bad in itself, but many companies implement two common antipatterns when using them that cause them to do more harm than good:

Antipattern 1: Using it in Synchronous mode

If you are using Slack synchronously, turning on notifications at all hours and context switching to respond will kill the flow state of engineers and keep them continuously distracted at work. Chat apps, must be used asynchronously. Notifications are great as a way to bring awareness to important issues so they don’t get buried under all other messages in channels, but engineers should look at Slack around their own schedule, not reacting to notifications, and a company should foster an environment where engineers don’t feel pressure to respond immediately to any message.

A work chat app is also not the best tool to notify for emergencies as they may get drowned under other notifications. Instead, it is best to use a tool specifically for that purpose, such as Blameless or PagerDuty.

Antipattern 2: Using it as a layer of collaboration and context

Slack brands itself as a productivity platform, but the reality is that at its core, it is a chat application with some productivity features added in. This is very different from a productivity app with a chat feature baked in because the core functionality of any tool will dictate the type of use that it gets from users. 

Therefore many companies fall into the trap of using Slack as a jack of all trades for all things collaboration and getting context. But Slack being a chat app, information ends up being fragmented across multiple channels, and people getting bombarded with the same questions time and again.

In order to collaborate better and get context, it’s better to use relevant apps for each purpose which we will cover later. For example, to get context for your engineering architecture and services, a developer portal is ideal because it is a central pane where you can find all your services, who owns them, who they belong to, and the relationship between them, Slack can be used for this too, but it makes a very poor substitute that breaks flow state. A developer portal can also leverage integrations with other tools more seamlessly to bring further collaboration and a unified view of everything that’s happening within your services architecture.

Slack makes a poor layer to connect all other tools collaboratively. As Kevin Kwok bluntly puts it in his great post The Arc of Collaboration: “Slack is not air traffic control that coordinates everything. It’s 911 for when everything falls apart.”

Project management software

Project management software like Basecamp, ClickUp, and others are designed to facilitate communication and planning around a specific project. This means that your timelines, documents, conversation, and everything relevant to that project lives within one project space. Project management software is by nature asynchronous, so you won’t have the same issues you have with Slack by default. In fact, some companies have even gone as far as to ditch Slack completely and just use Basecamp to communicate instead.

Email

Email is seen as an antiquated form of communication, but it has its time and place. For example, company announcements or legal documents are better served via email than they are via Slack. Additionally, if the objective is to ensure that people don’t get distracted by your Slack notifications and/or you need to send a long, structured message, email is a better option.

The nature of email communication is also heavily dependent on the client you are using for it. For example, Superhuman is an email client that claims to dramatically enhance productivity with powerful AI features. Tools like this have the potential to bring email back to the forefront of communication with features that use modern technology.

Internal wikis

Internal wikis like Notion or Confluence are a great way to have structured documentation in your organization. If a wiki is well-written, organized, and up-to-date, it is a good resource to search for information.

The problem with wikis is that it takes a substantial amount of work to keep them up to date and organized in a way where it’s easy for everyone to find information. Typical challenges include wikis with multiple duplicate documents, information that’s hard to search for, and outdated documentation. Wikis also generally don’t provide real-time updates, so they are not the best place to get updates on things like the status of services or up-to-date relationships between services — this is where an internal developer portal can help.

Note: It is worth mentioning here that the best place to document your application is within the source code using markdown language such as README files. This makes it easier for developers to keep documentation up to date as part of the software release process. We consider this communication as your work speaking for itself, as mentioned above.

Developer portals

We mentioned how Slack and documentation are usually the places where people go to find answers at an organization. Slack is a fragmented resource for finding answers, and having engineers continuously answer the same questions adds friction. An internal wiki is better, but it requires a substantial amount of effort to keep up to date with fresh information.

Many modern engineering environments are home to tens, if not hundreds, of services, created and maintained by various teams. Keeping track of each of these services — as well as their ownership, related resources, diagrams, maturity assessment, documentation, and relationships — is very time-consuming and difficult to do with a wiki alone.

Instead, a developer portal can be used as an engineering hub where developers can go to get the most up-to-date and relevant information about services and the relationship between them. A developer portal also provides links to all relevant resources in one place and gives you a real-time glimpse of the status of the services. Developer portals also make it easier to onboard new joiners because they know where to get all the information that relates to their team and services.

In addition, internal developer portals enable you to trigger self-service actions to perform automation and other tasks that may take away from the focus of development, as well as creating new services from templates with everything that’s needed to get started, significantly improving the flow of work. 

Company updates done asynchronously

The allure of having company meetings to make announcements is that if this isn’t done, people won’t get context, and if you do it asynchronously, people may not read it. So how do you balance having asynchronous company updates that lead to more flow state while ensuring that people are actually getting the information they need? 

Here are some ideas: 

• Condense the announcements. Make them easy to digest and quick to read.
• You can keep the all-hands and company-wide meetings, but ensure that you also record them. Better yet, condense them into a few bullet points that can be sent out alongside the recording to people who didn’t attend.
• Add company updates to your board as a recurring task that people need to complete before the week is over. Update the task with the current update every week. This way, people review it when they can, rather than at a specific time, and it is part of their week’s tasks.
• Consider leveraging AI tools to condense information or take notes in meetings. (At the time of writing this, I would also appoint someone to review these outlines because AI still hallucinates plenty.)

3. Synchronous communication

As we mentioned above, engineering is best served with asynchronous communication to minimize the amount of interruptions and maximize flow. That being said, there are some cases where synchronous communication may be preferable, for example:

• Meetings — Some examples include planning sessions, discussing topics in detail to make informed decisions, teaching/mentorship for small groups, clarifying complex issues, and building rapport with colleagues. 
• Emergencies — anything that requires immediate attention.

‍

In this section, we explore how to facilitate meetings that support a positive developer experience and improve flow state

Meetings

How and when to set up meetings?

There are three things to consider when setting up meetings:

1. Meetings are a last resort

‍

‍

Before setting up a meeting, ask yourself if whatever needs to be communicated or discussed can be done asynchronously. No matter how well we time our meetings, they are bound to interrupt the flow for at least one or more of your attendees, so if the meeting is just to share something and doesn’t require discussion, try and do it asynchronously.

2. All participants must take an active part in the meeting 

If you are setting up a meeting where only one or two people are going to be talking, then it makes more sense for them to discuss the topic together and write down the outcomes for others to read asynchronously. Remember that an hour meeting with ten people is actually a ten-hour meeting.

It is the responsibility of those who set the meeting to ensure all members take an active part in the discussion — some people are shy, especially in engineering teams, so they may not say anything for fear of being wrong, interrupting, or being overpowered by a bigger, more extroverted personality in the room.

If you are not sure who can contribute value to a meeting, add a note to your invite asking people not to attend unless they are going to participate actively. Make this explicit by saying something like, “Please only attend if you have opinions or questions on this topic. Outcomes will be shared with everyone on the invite after the meeting.” 

It is important to actively discourage people from attending meetings where they are not going to take an active part. This is because even when you make it optional, some people will feel pressured to join so they can show their investment in the company. Attending a meeting as a passive observer provides no value to the company, especially if you were distracted from work as a consequence of the meeting!

3. Participants must be familiar with the topic

If you need to make a decision in a meeting, it is very important that everyone is familiar with the topic being discussed to prevent uninformed and potentially harmful outcomes. Keep decision-making meetings small; engineering should be more of a representative meritocracy rather than a direct democracy. You don’t need company-wide referendums to make every decision, as that will just slow things down.

I’ve been in meetings where a staggering forty people were invited to make decisions on very technical topics they were not familiar with at all, myself included. The best thing that can happen in this kind of meeting is that most of those invited don’t say anything, especially those smart enough to know that having an opinion on something they don’t know anything about creates bad outcomes. The worst thing that can happen is that those with a big ego take over the meeting and pass on knee-jerk judgment on things they don’t understand, and that’s how bad decisions get made. 

If you need to have a discussion about a complex topic with the engineers in your organization, send them information ahead of time so they can get familiar with what you need to discuss, and keep these meetings small in case you need to give context or explain anything before deciding anything.

Exception: meetings that build rapport

Social meetings are underrated. Depending on your personality type or cultural background, you may need more or less interaction with your colleagues to build rapport and trust them. For example, Northern European and North American cultures are more task-based and have a higher implicit trust when working with others. Meanwhile, employees in places like China, Japan, Spain, and other countries require more interaction to build this trust. Hence you will probably see more of a heavy emphasis on building personal relationships in these cultures. The book Culture Map by Erin Mayer tackles this topic in great detail and it is highly recommended reading for working with multicultural teams. 

‍

At any rate, even for the most task-based societies, it is very important to interact with colleagues in order to cement relationships and get to know colleagues better. It’s crucial to have social meetings or off-sites from time to time. I find these meetings are better with small groups of people, no more than four or five, and they can be done as 1:1s too.

Emergencies!

If your engineers are constantly running around because everything is urgent, then it’s safe to say that nothing is urgent and that planning, managing, or the vision hasn’t been properly communicated or established by leadership.

Work towards minimizing the number of emergencies and incident responses your engineers need to respond to by taking preventative measures and rotating the responsibility around your team. Ensure that those who can actually fix the issues at the root also respond to these emergencies so they don’t happen as often. Don’t favor continuous urgency, favor prevention strategies.

Finally, don’t use Slack as a reliable medium to notify for emergencies as they may get drowned by other less important notifications. Use dedicated tools for this purpose, like PagerDuty, instead. 

Example metrics you can use to improve the quality of communication

In this series, we like to wrap up each article with a set of metrics or questions that you can use to help optimize DevEx within the context of the topic at hand. 

For communication purposes, these are questions that you can ask your team and metrics you can measure to get a better sense of how you are performing. They are just examples. You may need a few, or you may need more depending on your company and use case.

• How many meetings on your calendar could be done asynchronously?
• How many members per meeting are not relevant to the discussion but could benefit from learning outcomes asynchronously? Consider cutting down the number of participants in these meetings and communicating outcomes with them later.
• Are people getting the right context before joining a meeting?
• Are all people in a meeting participating? Why not? Do they need to be there?
• Do all Slack channels have the right description and context for people to know what to use them for?
• Are engineers responding to notifications immediately, forcing them to context switch?
• Classify recurring types of conversations and communication happening in Slack channels. Could these conversations be better translated into documentation, a developer portal, a Kanban board, or any other more adequate tool?
• Are teams talking to each other instead of using tools or API abstractions? No need to talk if your API works well and is intuitive. Use work to communicate, not words.
• Are different teams or team members talking all the time because the work is hard to understand and use?
• Measure the number of repositories without adequate documentation. Why are things not getting documented?
• Are the files in your application well organized and intuitive to understand?
• Is your application packaged in a container or with any other packaging manager like Nix? 
• Explore the documentation of your tooling. Is it contextual? Is it too long? Documentation that’s too long (or has too many steps) may indicate bad design.
• Do you have a universal source of truth for engineering context? → like an internal developer portal, for people to go in and get a live and unified view of your engineering resources in one place?
• Are you using the right collaboration tools for each purpose? → As opposed to using something like Slack as a jack of all trades.

Conclusion

Engineering communication that improves developer experience is communication that helps developers to easily get in and maintain flow state. Therefore it is paramount that our work is well designed so it can speak for itself so when our colleagues and other teams need to use it, they don't need to talk to anyone to comprehend the intent and usability and can easily focus on their domain. When collaborating with other teams or colleagues, asynchronous communication is favored over synchronous communication to reduce friction and distractions. To improve collaboration, it is important to use the right tools to maximize collaboration and provide context and information quickly and with the least amount of friction as possible.

About the Author

Fernando Villalba is our Developer Relations at OpsLevel, he has over a decade of miscellaneous IT experience. He started in IT support ("Have you tried turning it on and off?"), veered to become a SysAdmin ("Don't you dare turn it off") and later segued into DevOps type of roles ("Destroy and replace!"). He has been a consultant for various multi-billion dollar organizations helping them achieve their highest potential with their DevOps processes. Now he is passionate about platform engineering, developer portals and DevEx, which he feels is where the future of software delivery shines brightest.

Follow Fernando Villalba in LinkedIn or Twitter

‍

‍

‍