Are you a bad interface between colleagues and your code?

Bob Salmon

As developers we need to care as much about how we communicate with your colleagues as we do about our code.

As digital professionals we are familiar with worrying about a graphic user interface or some other type of interface between a user and a computer.  However, sometimes the interface is you – not between the computer and someone who will use it, but between the computer and someone who needs to understand it.

Just as programmers need to develop their skills in building computer systems, they also need to know how to explain those systems to others.

As developers we are the interface between management and the technology they rely on for business success.

Others need to understand your work

There are several types of stakeholders who might need to understand the development project you’re working on. People such as:

  • Potential customers who need to understand your approach enough so that they have enough confidence in you before they will sign up;
  • Customers who need to see that you’ve done what was agreed before they will sign the project off and pay you;
  • Managers who need to understand why option A is riskier / cheaper / etc. than option B, before deciding between them;
  • Fellow programmers who need to understand an area of the system you’re an expert in before they can work on it (otherwise you’re doomed to always be the person who works in that area).

Having knowledge of a system in your head is terrific, but it’s not enough. You are the interface between others and that knowledge of the system.

How to be a better interface between colleagues and your code

Just as a GUI can be a good interface or a poor one, your effectiveness can vary as an interface to others knowledge of a system.

A good user interface needs to consider the needs and abilities of the user – it’s meant to be their interface after all and not yours. So, If you don’t pay attention to the person you are speaking to, you can come across as tedious, go over their head or patronise them.

What does your user know?

What do they already know of the subject matter and to what level of detail? What similar things do they already know? Is there something else that they’re already familiar with that could help such as development practices, customers, markets or technologies?

What is your user’s objective?

Where does the user need to get to? What do they need to understand and to what level of detail? It’s worth digging into things a bit here. For instance, a user who is asking for a lot of detail might not be all that interested in the particular, but actually, they need you to address their fears that you’re going to build the right thing. They think all this detail is the best means to their real objective, but maybe it’s not. Going through the risks explicitly might be a more effective way of getting them to where they need to be.

Think about your presentation style

Think about structure, both conceptually (how all the bits that need talking about fit together) and over time (what you talk about when). When creating a GUI, you think about visual hierarchy, typography, flow and so on. Just as it’s not a good idea to present every element of a system on screen all at once, it’s rarely a good idea to attempt to dump all the details out of your head into someone else’s.

Some things to consider are:

  • What are the key concepts you are trying to explain?
  • What is the easiest thing to understand first?
  • Why is something important?
  • Are there concrete examples that bring together all the abstract stuff?

It is the same as designing an interface – arranging its elements (including leaving some bits out) so that the whole is as efficient as possible.

What is the best thing to convey a particular bit of information? Is it words on their own, or do you need to show a diagram or, e.g. an example bit of XML, and then talk about it?

Being the interface likely doesn’t come naturally, but then you probably weren’t immediately fluent in your current development technologies and tools. Instead, you worked on those skills over time – something you should do with your communication skills.

Why bother?

Customers, managers and colleagues can be annoying sometimes, for a variety of reasons. If you communicate with them effectively, so that they know what they need to know when they need to know it, and for as little effort on their part as possible, then you are reducing the number of reasons why they should be annoying.

They might still ask for unreasonable things by ridiculous deadlines, but now that’s despite your best efforts to help them do otherwise.


Just as it’s essential to design and build stuff, it’s important to explain it to others – as well as making the world a better place, it can be in your interests.

Know your user – what state they’re currently in and what they need to get to – is vital in designing the interface to fit your user. Notice how this article could have been phrased in more everyday language.

However, because I’m targeting it at a technical audience who might be sceptical of why and how to communicate well, I’ve phrased it in a technical language such as interfaces, states, bugs and so on.

You can have bugs in your explanations, but like designing and building, explaining is a skill you can work on so you can hopefully produce fewer bugs in the future.

Stock Photos from twobee/Shutterstock