How to apply API design to boost your team’s communication

As a CTO, you probably design or review the APIs that your team creates. In fact, most startup CTOs have strong opinions about what makes a good (and bad) API, drawing on years of past experience for their design criteria. They’ve spent decades using, creating and specifying APIs, and know the importance of getting it right.

Like many things, when an API is clear and works as expected, it’s a joy to use. But when an API is bad, it’s awful. Personally, I’ve wasted too many years of my life wrestling with poorly documented, unintuitive and confusing APIs (going back to the days of shared libraries and DLLs!).

In the late-2000’s the concept of “designing an API for human use” arose and API designers realized that well-thought-out APIs were worth investing in. With that in mind, it’s useful to look at team communication in the same way as designing an API because you may find that more documentation or design is needed.

API design is an example of communication design: planning how resources will work together, what the allowed messages are and which channels are used. Designing your team API is a similar task, yet one that most CTOs ignore; hoping that “everyone will just work together to do the right thing.”

This rarely works out well, and I’ve seen many talented engineers suffer under this leadership mistake.

Why is communication design needed?

Communication design creates a safe, comfortable and sane place for your engineers to focus on technical work. For many of them, communication is one of the biggest challenges they face, and is a significant dissatisfier. At CTO Craft we hear more complaints and frustrations about humans than technology, and a lack of explicit communication design is often at the heart of these problems.

Let’s be clear: there will be communication standards for your team, but if you didn’t design them, your team informally created them over time. These are the cultural norms that your team operates within; they are almost always unspoken and are considered “tribal knowledge”. New members learn by watching others, and for better or worse, will use the communication standards the team is already using. Changing these norms can be difficult and will require more than a memo stating, “This is the way we do things from now on.” It will require that you start with yourself.

Who’s communicating with whom?

It helps to start by listing some common actors and channels to consider. Your team API strategy should take into account communication between:

1. You and individual engineers
2. You and the team as a whole
3. Engineers within the same team
4. Engineers on different teams
5. You and your boss
6. Your boss and individual engineers

This list is not exhaustive. As you examine own team, you may find other places where communication design is needed.

For each group, consider these eight design questions:

1. Is there a primary channel/platform for communication?
2. What are the primary topics that need to be discussed?
3. How frequently should they communicate?
4. How should problems/exceptions be handled?
5. When is structured communication preferred? When is ad-hoc communication preferred?
6. What communication do you need to be aware of?
7. What questions can each party ask each other?
8. What requests is each party allowed to make of each other?

Again, this isn’t a comprehensive set of questions. The goal is not to micromanage your team’s communication or become overly-controlling, but as communication design is concerned with who, what, where, when, why and how often systems communicate, you can see how it becomes a lot like API design.

An example

You and your engineers individually need to communicate to deliver work, so you need to design your communications. Let’s see how the eight questions work in this situation.

Question 1: What is the primary channel/platform for communication?

Your primary communication channel with an engineer should be a private 1:1 meeting. This meeting is the foundation on which other communication, and the relationship as a whole, is based.

Question 2: What are the primary topics that need to be discussed?

Designing the primary topics for your 1:1 meeting is a key part of designing the communication. Your topics will flow from another design decision: what is your goal for the meeting?

For example, if your goal is to get information about each project,, your 1:1 may look like a status update. If your goal is to motivate the engineer, you may spend time explaining how a project contributes to company goals. If your goal is to improve the relationship with the engineer, you may spend time just getting to know them, or allowing them to control the meeting topics.

For my 1:1 meetings, my goal is to build great work relationships with my engineers. This has led me to choose 1:1 topics such as:

1. Learning about the engineers goals, aspirations and family life
2. Discussing career paths and training opportunities
3. Discussing expectations about what needs to be accomplished
4. Answering questions about project requirements
5. Giving honest feedback (Radical Candor, style)
6. Asking for honest feedback, so I can improve

Your list of topics may be different, but it’s important to communicate what topics are fair game for the meeting, and which ones are out of bounds.

Question 3: How frequently should they communicate?

This will vary according to your team size, your relationship with the engineer, their skill and seniority. Common frequencies include weekly, bi-weekly or monthly meetings. Not all engineers will need (or want) the same design. New team members should meet weekly, as should senior engineers or those leading key initiatives. Since your time is limited, it’s more important to optimize for consistency over frequency, so design a schedule that is workable.

Question 4: How should problems/exceptions be handled?

This is a crucial point, and if you don’t design the communication properly, your results will vary wildly. Unfortunately, when an engineer makes the wrong decision here, it can change your perception of their performance. Instead of allowing guesswork, or saying, “just use your best judgment”, discuss and design the communication around problems, exceptions and emergencies. For example, how should your engineer alert you of blockers or obstacles? What if they find they’ve exceeded a story or project estimate? Should they call, text or email even if very late? When is walking into the office the right course of action?

Question 5: When is structured communication preferred? When is ad-hoc communication preferred?

There’s a time for both, but don’t leave this to chance. Create an agenda and a goal for your regular 1:1 meetings and other structured communications (status reports, time-sheets, project updates, etc). Or, you might prefer to design an “open door” policy, that allows for unstructured, ad-hoc communication at specific times during the week. Your team will then know what to expect.

Question 6: What communication do you need to be aware of?

When a new engineer on my team started working directly with external customers, I wanted to know about it. When my engineers were receiving requests from other managers, I wanted to know about it. Again, this isn’t because I’m a micromanaging jerk, but because you can’t manage what you can’t see. Designing visibility into your communication channels is like setting up a monitoring server for your application. You need to decide what you want visibility into and how you’ll get it. In this case, I told my engineers to notify me if another manager sent them a task. Sometimes I would approve it, sometimes I needed to discuss the task with the other manager. Either way, my engineer wasn’t left wondering what to do with the request. This serves to prevent your engineers from being pushed off course by external distractions.

Question 7: What questions can each party ask each other?

Creating ground rules about who can ask your engineers for a status report and an estimate or a timeline, is an important part of protecting your team. In addition, clarify what kind of questions your engineers can ask you and what you will ask them. In the past I have allowed my engineers to ask: “Why are we doing this project?” in our 1:1 and team meetings, but crucially, made it clear that this was not to be asked in front of a customer. Many young engineers don’t receive this guidance and therefore sabotage their career by inadvertently offending a client or executive in public.

Question 8: What requests is each party allowed to make of each other?

I assigned my engineers work and I allowed them to assign me tasks. I also encouraged them to assign each other tasks and collaborate on them. I did this because I believe in a participatory style of management and found it to work well with skilled workers. You may have a different style and a different communication design, and that’s fine. No matter what approach you choose, communicating who can make requests of whom, and what type of requests can be made, is vital. It gives your team the ability to service the right requests and decline the wrong ones. It’s also important to communicate how they should decline them and when to get you involved. In this situation you might tell them to send all denied requests directly to you and you will handle them. Whatever you choose, make sure you intentionally design it and discuss it with your team.

It’s not about control, it’s about design

Unlike an API, your team won’t follow your design perfectly. You shouldn’t expect them to. But you can use use their feedback to revise and improve the communication design. They already have norms around how they communicate, as well as existing relationships, preferences and styles. Tread lightly, as being heavy handed can cause you to look like a micromanaging boss.

Like so many things in leadership, start with yourself. Examine your communications and think about how you could design them to meet your goals. Discuss with your team the idea of communication design and ask for their feedback and goals in designing a great communication structure. This kind of collaboration and iteration is at the heart of agile philosophy.

Your turn

I’ve explained the various aspects of communication design, now the spotlight is on you. Consider how effectively your team communicates and where you need a different design. Use the eight questions outlined above to guide your design thinking and remember to collaborate with your team to get buy-in. After all, a design that no-one uses is worse than useless — it’s wasteful. In the end you’ll have to design, document and demonstrate how to communicate.

Your team won’t always remember what you say, but they will always remember what you do.