In this episode, Thomas Betts talks with Jacqui Read about communication patterns. Similar to software and architecture patterns, these provide guidance for how to improve communication by knowing your audience and what you need to explain to them.
Key Takeaways
- The ability to communicate effectively has often been called a "soft skill," but to progress in your career you really need to develop this as a "core skill."
- Take the time to simplify diagrams to make it easier for someone to understand, often by removing what isn’t necessary.
- The C4 Model is one way of creating a series of related diagrams to describe a system. Use patterns to help the reader understand the relationship between diagrams, such as a consistent blue box identifying the context.
- Color in diagrams can be useful, but must be used thoughtfully to avoid confusing your audience. Sometimes black and white, or maybe blue, is the best option.
- Create perspective-driven documentation where you're really focusing on who you are communicating with and why.
Subscribe on:
Transcript
Introduction
Thomas Betts: Hello and welcome to another episode of the InfoQ podcast. If you believe like I do that every software problem is fundamentally a communication problem, then you'll be excited about today's guest.
Jacqui Read is an internationally recognized solution, enterprise architect and author of Communication Patterns: A Guide for Developers and Architects. She specializes in assisting businesses to create and enhance architecture practices, construct evolutionary architectures and untangle and extract value from data and knowledge.
Jacqui, welcome to the InfoQ podcast.
Jacqui Read: Thank you very much. It's really great to be here.
Every software problem is really a communication problem [00:51]
Thomas Betts: So let's start with what I mentioned in the intro. Do you agree that every software problem can be traced back to a communication problem?
Jacqui Read: I do. I think that below all of the software, all of the hardware, it's all down to people and people need to communicate with each other. And so if people can't communicate with each other well and teams can't communicate well, then how can the software work well? I've heard lots of people say that they can see problems between interfaces of say one service and another just by the fact that the two teams don't talk to each other relating to Conway's law and things like that. So yes, I do believe that communication and good communication is the way to actually get good software.
Architects need to be great communicators [01:39]
Thomas Betts: Many of our listeners are software architects or they have architecture responsibilities, even if it's not their official title. Why is it critical for those roles to have great communication skills?
Jacqui Read: I think that people who are in that kind of role, even if you don't have the title of architect, you are kind of the bridge between the different people in the company. And maybe you are bridging between very highly technical people and people who are slightly technical or maybe you are bridging between technical and the business people who have absolutely no understanding of the technology at all. And that is such an important link between those two.
You might not consider yourself to be something like an enterprise architect, which a lot of people think of as the bridge between business and technical, but it's not just that kind of level that really needs to communicate. It's every level. It's going between the developers and your product owner. That's not normally done by anybody at enterprise level. So yes, if you are working in the architecture space, communication is really, really important, especially if you want to actually move ahead in your role as well.
"Soft skills" are really hard, and should be considered "core skills" [02:59]
Thomas Betts: Yes, I think we tend to focus especially on engineering roles, as having those very technical skills and communication and writing and talking to other people is relegated to the "soft skills" category. Can you speak more about where you think it's important to level up your soft skills for being an architect?
Jacqui Read: Well, first of all, I think that soft skills really are actually more the harder skills for people to learn. And so I don't call them soft skills, I call them core skills because they really are the skills that everybody needs if they want to progress in their careers. Even if you are determined to stick to the technical route. If you are the one who is able to communicate, then you are going to be the one who is promoted, who's a team lead or a technical lead rather than someone who's part of the team. So anyone who wants to progress their career really needs these core skills.
Communication patterns are similar to software and architecture patterns [3:56]
Thomas Betts: So I'm reading your book and I like the title is Communication Patterns. I think it plays on the idea of re patterns and architecture patterns that it's not... This is the way you have to do it, but there are almost templates. Can you speak more about why you went with that approach for writing the book and talking about these different patterns that people can follow?
Jacqui Read: Yes, so the fact that they're actually hard skills to learn, these core skills, I think it needs people to have a nice format that they are familiar with and people working in technology recognize patterns and anti-patterns. That's why I went down this route so that people could use these and apply them. And another really good thing about patterns and anti-patterns is that it doesn't just say this is what you should always do because there's no silver bullets.
We know, in software and software architecture, and so we look at these patterns and anti-patterns and we can see, oh, actually yes, usually this is the thing to do, but just in some cases this probably won't work and we're going to have to tweak it or do something slightly different. So that was the main aim and it also means that everything's packaged up into small bits, so you don't have to sit down and read the whole book at one go. You can dip in and out and read one pattern at a time if you wanted to.
Thomas Betts: It's almost like that reference, like if you're struggling with a specific situation, you can find that in the book just like if I'm having a situation with trying to get my architecture to work and how do I get these two services to communicate better, there's patterns I can go and look for.
Four categories of communication patterns [05:31]
Thomas Betts: I like that you have the patterns and anti-patterns and you said that it's always context specific. Maybe I should use this, maybe I shouldn't use that. Can you give some of the high level "it depends" criteria that we want to look at when we're determining which patterns to use in a given context?
Jacqui Read: It's always interesting with these, so I divided the book up into four sections. So there's the visual section, so if you are looking for anything to do with diagrams and other visuals, then you can have a look in that one. Then one of the sections is, so I called it multimodal because it's written and verbal and nonverbal. And so if you are struggling to communicate with people in different ways in person or it also talks about if you are talking to people via cameras and things, then that's the place to look at.
Then also if you are looking at remote work, there's a whole section on communicating remotely. And then the last one is on knowledge. So you've got those four areas and when it comes down to thinking about the really more high level, it depends, there isn't really anything that will cover absolutely everything in the communication sphere.
But once you start drilling down into things, you can look at things like, oh, should I be communicating synchronously or asynchronously in this case? And I've got a few rules of thumb that you can use in that. That is things like announcements tend to be better asynchronously unless it's something really important, something that people are really going to want to ask questions about straight away and want quick feedback, in which case you should then be doing it synchronously. So you've got those rules of thumb, but then oh, but do this in this case.
Thomas Betts: I think the synchronous and asynchronous is a good parallel because we hear those terms associated with software, but I think good software models human behavior and it makes it more intuitive to use. And so if you start thinking how are the teams communicating, how is the software communicating and what's the right structure here? Am I going to interrupt somebody and talk to them synchronously and have to wait for their response or is it a broadcast type of message? So that's really a useful distinction, again, it's very high level, but that's just one of the places.
Remote communication patterns [07:54]
Thomas Betts: I think you also started talking about the different audiences that you're speaking to. I think when you mentioned remote work, tend to have different interaction patterns. More people are working remotely than they were three, four years ago. And it took a while for some people to adapt to that scenario. Why is that? Why do we not have the same things we used to do when we were in the office? Why don't they work anymore when people are on a screen?
Jacqui Read: Yes, it's quite interesting that one, and I cover quite a few things in the remote section, but also in the verbal and non-verbal because when we're face-to-face it’s an awful lot easier to read someone's body language and their facial expressions. So when you either can't see them at all or you can only see part of them on the camera, it can be a lot harder to understand what people really mean and when you are the one who's trying to communicate maybe you doing an important presentation, then there are lots of things you need to take into account to try and get your message across, like making sure that you are keeping gestures inside of your camera area, but also making sure that your gestures are visible to people. So it's thinking about that sort of rectangle and often when you're on camera you have to give a lot more energy into things for people to actually feel that.
Whereas if you're in the same room together, it's much easier to communicate those things to people just using your body language and your facial expressions. And you've also got this thing called ... People have called it Zoom fatigue, but it's not just for Zoom, it's for anything where you are staring at the screen. So if you are looking at the screen and you can see a picture of you sitting there, that's not natural at all. Imagine if you were walking around and someone was just holding up a mirror to you all day and you saw your face all day. That's not natural.
And so there's a few tips in there like turning off your own video, which can really help. It's surprising how much that helps. And also just taking time to look away from this huge wall of faces if everyone has got their camera on, you've just got all these people looking at you and that's not normal. If you think about a meeting, unless you are actually up on a stage and you've got everyone looking at you, that's normal. But if you are in a meeting, people look in different directions at different times. So you get a lot of fatigue from just interacting with people via a computer compared to face-to-face.
Thomas Betts: Yes, I think that's one of those things I saw in the book that felt almost obvious because we talked about that years ago, but people tend to get into these little ruts and patterns of behavior and we were talking about Zoom fatigue in 2021 and then we stopped talking about it and it just became the way things are working. Some companies have adapted policies to say, oh, we're going to schedule meetings not back to back.
There's going to be a five-minute gap as a default start time because you used to have that time when you had to run into another conference room and now it's like I switch off one Zoom and I switch on another. So really being cognizant of that and I think it's useful sometimes, even if it sounds like advice you've heard, sometimes it's useful to ... Just like going back to the gang of four patterns, it's useful to read those good patterns to follow because sometimes it's just a needed reminder of how to behave and how to be productive.
Jacqui Read: Yes, definitely.
Visual communication anti-patterns [11:28]
Thomas Betts: So you said the first section of the book was on visual patterns. Architects create diagrams. I think some companies, that's the primary task of architects. It might be the only thing that people associate with the architects. There's an a architecture team, especially enterprise architects, so I understand why that was the first section of the book dedicated to visual communication. Let's start with the bad news first. What are some anti-patterns for visual communication?
Jacqui Read: There's quite a few in there. You get some interesting ones. One of them I tend to refer to as a spider's web where you get these diagrams where there's just boxes everywhere, lines everywhere. The lines tend to be crossing a lot, possibly even crossing over the boxes and there's just labels everywhere and you're not really sure which label applies to which line. I've seen so many diagrams like that, and even if people can work out what it does mean, you're still using up all their mental energy to do that and people aren't going to be happy about that. But it's really easy for people to misunderstand something. And if somebody doesn't understand something, you can end up a couple of months down the line with something really expensive that needs fixing, especially if it's a development team's gone completely the wrong direction for some reason.
So when we've got a diagram like that, there's a few things you can do. Like if you try moving the boxes around, you can normally get it looking a bit better. A lot of the patterns and anti-patterns that are in there, I say you need to remove the stuff that shouldn't be in that diagram because very often people just try to put all the information into one diagram. And so either removing that information or moving it into another diagram is key to fixing a lot of the problems in diagrams. But you can also use what's called orthogonal lines. So instead of just having lines going straight from one box to the other, which can be of course diagonal or whatever the orthogonal lines are the ones where you get the right angles in it, and those mean that you have a lot more control over in what direction it goes.
You can normally pull them around and get those in a good place. And then the other big tip with these spider's webs is that if you standardize where you put the label, it makes it a lot easier for people to read the diagram. So if you put it always roughly in the middle or always at the beginning of the arrow, that means that people can see very easily which label applies to which. But of course there's going to be exceptions to that. Sometimes you're going to have a part of the diagram that's really cluttered or there's just not space for something. And in that case you need to put the label where it's easy to read. So as I said, there's no definites, there's no silver bullets.
Thomas Betts: One of the key points, again, just a nice reminder was remove anything that you don't need to talk about. And sometimes it's put it on a different diagram. Sometimes you have to accept there needs to be two. But the tendency of I need to over communicate, I need to share everything can get in your way. Blaise Pascal, "I didn't have time to write a short letter, so I wrote this long one instead."
It's easy to do the thing with all the clutter. It takes intentional thought to say, okay, how do I clean this up? How do I express what I'm trying to get to? Which goes to I think audience context and purpose. Who are you communicating with? What are you trying to convey to them? What's important? Let's go to the idea of splitting it out into multiple diagrams. What are some good ways of how do you take your big diagram and decompose it into logical sections that are easier to understand?
Decomposing large diagrams for readability [15:20]
Jacqui Read: Well, one way to sort out another anti-pattern, there is these huge diagrams where you just have every box everywhere and it's all tiny and you can't actually read it. And one way that you can help with that is to split it into different levels. And a good way to learn how to do that is to use something like the C4 model where it has a context level at the highest level and then it breaks it down. But the way it's done is that, say when you've got the context level, which just shows your system and the users and external systems on it, you'll have a dark blue box.
Typically, you can do what you want as long as you've got a key, that's fine, but that's your main system. And then when you break that down into the container level, which is the next level, that blue box is shown as a dotted line around the edge of your diagram, and so people can see how the diagrams are connected to each other.
So when you've got those obvious and explicit connections between your diagrams, it doesn't matter that your information isn't all in that one diagram. It's then easy for people to navigate between your diagrams. Also, if you are looking at trying to take information out of a diagram, maybe you've got a diagram that sometimes you want to show it to people who are interested in security. Other times you are showing it to more business minded people and you don't want all of those security protocols and stuff all over it.
If you create your diagram using layers and most software things like draw.io that will allow you to use layers, you can then just hide the information that you don't want. And that's also particularly useful if say you need to create your diagrams in say, more than one language as well. So you need to do it in French or Spanish or German or whatever. Then you can have all the layers in one diagram, and that means when you update the layer in English or whatever it is, then you know that, oh, I need to update this other layer or I need to get someone to update this other layer so that it's correct.
Color is important, but must be used correctly [17:37]
Thomas Betts: And you mentioned a blue box but said it didn't have to be blue. Let's talk a little bit about colors and other semantic information and how important it is to have those things be consistent. Going back to your idea, I think of make it easy for the reader to understand rather than having a rainbow chart because it looks like a lot of fun.
Jacqui Read: The key really that we're looking for here is making things easy to understand. Because people only have a certain amount of attention and energy that they can give to you, and we don't want misunderstanding. And color is actually an important part of that. Now, I said it didn't need to be blue, but blue can very often be the best color to use because it's one of the better ones when you are trying to print things, if you're actually going to print.
And it also can be one of the better ones for people who are colorblind. But I've got a whole anti-pattern and a pattern on color, but it talks about color blindness in there and there's lots of different things you can do, but the whole thing is about not relying on color to communicate. And so we're looking at using color when it means something and not just as decoration.
So if you've got lots of different colors in your diagram, even if you've got a key or a legend, it's too much mental energy for people to just keep looking back at that key. And so you need to only use the color that is needed to communicate. And so you need to reduce these colors down and make it really easy for people to understand. And if there isn't a meaning to your color, if you've just gone, oh, there's each things in my diagram, so I'm going to use eight different colors, that can be very overwhelming to people. And human brains look for patterns, and so people are going to waste energy trying to work out what the meaning is. So if there is no meaning to your color, just choose one of those colors and make all the boxes the same color if you want to have color.
Another tip is you could actually just use black and white. I know a lot of people kind of shy away from that. But if you're using black and white when you want to really highlight something to people, when that one thing is colored in, then that's really obvious. And so that could be really, really useful. But when you're considering people who are colorblind, you can use a lot of different free simulators which are out there, especially if you're working with Web UIs and things. It's actually built into the dev tools in things like Firefox and Chrome.
But as I said before, it's all about not relying on color alone. And so you can use things like symbols. Maybe you use a tick with your green and a cross with your red, something like that. You can use labels as well. You can use pattern to distinguish between two different things if you think they're going to look very similar to someone who's colorblind. So there's lots of different ways that you can help people without just thinking, oh, I'll avoid red and green. Unfortunately it's not that simple.
Thomas Betts: And I think even the black and white, you mentioned sometimes having different levels of contrast. Someone pointed out that Excel, the grid lines between the cells aren't black because that would give them the same weight as the text. They're a lighter shade of gray. You want to know them because it's useful to distinguish between the cells, but you don't want them to have the same weight and therefore your brain thinks they're just as important as-
Jacqui Read: Yes, that's a really good example.
Writing patterns for architects [21:10]
Thomas Betts: But architecture isn't just about drawing. You mentioned early on about having to communicate with different business people, with security, with executives, and sometimes that comes down to reading and writing and speaking effectively. What are some other forms of written communication maybe that aren't just diagrams that architects should be getting better at creating?
Communicating knowledge [21:31]
Jacqui Read: Well, one part of the book is dedicated to communicating knowledge. And I called it that rather than documentation, because knowledge isn't just about documentation. And so this is all about how we can make sure that we haven't got all the knowledge either just in people's heads or maybe it's only in one person's head. And we need to make all that implicit knowledge that's in someone's head into explicit knowledge as far as possible.
There's always going to be some things that really cannot be written down, and when it comes to that, you need to be looking at getting that person to be teaching or training other people to develop those sorts of skills. Things like leadership that people try to write a lot of stuff down, but I think there's at least some things that really can't be written down. And so there's a whole section dedicated to how we can communicate in these different ways.
There's things like thinking about things as products rather than projects. Because when we store information related just to projects, it tends to get lost or forgotten. So a project works on a product, but you may have many projects working on that product over time, or maybe you have more than one going on at a time. And one example of that of course, is when you might be working using distributed architecture and you have lots of different teams, you can think of it like that. And so if all this information is only stored related to that project or team, it can very easily get lost, get duplicated.
And when that happens, then you're probably going to end up missing things and undoing good things, not doing the right things when it comes to future projects that are working on that product. And you also don't get that kind of overview of everything. So you understand how everything's fitting together and where improvements can be made. That's one big thing.
Perspective-driven documentation [23:48]
Another one that I talked about is what I call perspective-driven documentation. And I didn't want to call it anything to do with views because the word view is really overloaded when it comes to architecture. But if you are doing perspective-driven documentation, you're really focusing on who you are communicating with and why. And you are thinking, okay, this particular stakeholder needs this information, or maybe that you haven't been told what information they want, but you generally know that that stakeholder wants to know about X, Y and Z. And so you give them that perspective or view of that information.
And the idea really is that you would use maybe a wiki or something like that to actually create that one-page view or perspective for that person, which addresses their needs.
And maybe one of those things in there is actually used in other people's perspectives as well. And so you would embed it in all the different ones if you wanted everybody to see when things were changed. So you're looking at applying things like the dry principle to this. I find that a lot of the principles that work well in code also apply well to architecture and even business as well. So it is worth thinking about applying these things like single responsibility principle that applies well to diagrams as well. So as I was talking about before, but of course again, these things are ... It depends, and we can't just blindly apply them everywhere.
So there's lots of different things that you can do to try and aid your knowledge communication, which will help you to understand your software a lot better. Because if you don't understand the software, you haven't really got hope of improving it, especially if you've say, got legacy software that you want to recreate. If you don't understand that legacy software, then you haven't got hope of creating something better, whatever you do.
Thomas Betts: Yes, I think that goes to the idea of you sometimes get better at knowing a product or knowing a subject when you have to teach it because you have to do enough research so that you feel confident getting up in front of a group and presenting what you've learned. It causes you to have more depth on the topic than if you've just learned it for yourself. So I like the idea that by thinking about different people's viewpoints, "How do I explain this more?" you get a better understanding and then that will probably lead to better architectural decisions, better software in the end.
Jacqui Read: Yes, definitely.
Communicate architectural decisions with ADRs [26:32]
Thomas Betts: So one of the things about communicating to other stakeholders that I know most architects deal with is architects make decisions. And I've talked before about architecture decision records. We've had guests on the show talking about it. How does that fit into these types of decisions? Is that something you cover in the book about why architects should write ADRs to communicate?
Jacqui Read: Yes. I talk about ADRs, architecture decision records in the book, and there's also some free resources on the book's website. So if you head over there, there are some free examples and templates that you can use for ADRs. But one of the things that I really think about ADRs is that the fact that they're called architecture decision records makes a lot of people think that they shouldn't be involved in it if they're not an architect or acting as an architect, where actually a lot of people make architecture-level decisions when they're not an architect.
And also there's all the people who should actually be consulted and know what decisions are being made. So don't be put off architecture decision records if you don't think that you are an architect, you should be involved in these. You should be at the very least reading them so that you understand.
But architecture decision records, essentially you write down the decision that's been made, but also the why. And that's the key point because if you have loads of documentation saying how you're going to do something, if you lost the how, if you've written down the why, you could recreate the how. But if you lose the why, then you can't recreate that. Nobody will ever know again why a decision was made if people can't remember it.
And the problems we get with that is that when you want to change that decision and you think, oh, but if I blindly change this decision, then I've got to accept that things might go awfully wrong. But also if I don't change it, I've got to blindly accept that decision and go, oh, it must have been the right decision to make. Whereas if we write down the context and if we write down what the options were and what was important to us, whether we use things like architecture characteristics, requirements, non-functional requirements, anything like that. If we write down what's important, what the options were and why we chose that option, it means that if that decision's ever according to question, we have a nice quick reference to go, oh, actually no, that's definitely still the right decision.
Or maybe you have a yearly review cycle and then you look at that and you think, oh, actually there's a new option now and that's much better than this current option. And then you can start creating a new decision record and work out whether it's worth the costs of changing that decision because of course there are going to be trade-offs to making that change as well. So you may have think, oh, this is a better option, but then you think, oh, actually it's going to cost us a million pounds or a million dollars to change, so I think we'll just stick with what we've got.
But when you record that, then the next time it's called into question, people go, "Oh yes, no, we're not going to make that change again, and we don't waste the time." It could take you weeks or months to actually come to a decision. And then if you don't want to do that again, every time you revisit that decision, if it takes two minutes to read your decision record, then that's going to be the place.
Communicating architectural concerns to business stakeholders [30:20]
Thomas Betts: Well, and you got into the subject of money because architects tend to focus on the technology, but a lot of times one factor, one criteria, one, it depends, trade-off is the cost. Build versus buy decisions are easy, but sometimes it's not that, sometimes it is. Does it make sense to re-architect what we're doing to put in a different technology? But architects usually aren't the ones of the purse strings that gets into communicating with the business.
Is it different when you want to write a decision and communicate that to business stakeholders to convince them you need to make this business decision of let's pay down the tech debt, re-architect things, but we don't get to build new features for the next six months while we're working on that?
Jacqui Read: Yes, the good thing about decision records is that shorter versions can be used to simply record a decision and the why. But you can also use them to help you to make the decision overall. And that means that you don't just have to go through it and then go and talk to the business. You can bring people in early on and say, look, here's our context. Do you agree with that? Here's what's really important. Do you agree with that? Are these things really important? Is something else more important? And if you collaborate and bring people in earlier and use everybody to help make that decision, then it's going to be a lot better than coming to a conclusion and then trying to convince the business that that's the right decision.
You do not need everyone to agree when making a decision [31:53]
There's also a few decision myths that I've put into the book which are quite interesting, and one of those is that everybody has to agree because especially when you've got a lot of people, you aren't necessarily always going to get that consensus.
Think about governments and things like that. They often stall on lots of different things because they need a certain level of consensus. And when you actually come to that and say, okay, I am committing to the outcome of this decision, I don't have to agree to it, it means that you don't get the block of not everybody agreeing. Obviously people still need to be able to say, I think this is unsafe, and the decision owner then needs to work with them on that. But if everyone can say whether they agree or disagree, but they need to commit to it, then it'd be much easier to make these decisions.
Encourage the creation of Business Decision Records [32:52]
And the other key thing really about decisions and the business is something that I've been talking about actually since I published the book, is something which I call business decision records. And that's more of an umbrella term, which these architecture decision records come under. Because I think writing down the why and the context and what the options were and things like that, it can be really useful in other parts of the business.
Think about setting strategy or when you are working in procurement, it doesn't need to be IT procurement. If we're writing these things down, when a contract is coming up for renewal, it's really easy to go and see, yes, we do want to renew this one, or oh, they're hiking the price up, should we be looking at something else? Are there new options? And even people like the C-suite and management, when they're setting policies and things, normally they have a sort of review process maybe every 12 months or something.
And if they wrote down a bit more information about why they made that decision and what's important, it'd be much easier for them to then review that decision every 12 months or maybe the market completely changes and they need to act quickly. If they've got all this stuff written down in their strategy decision record, whatever they want to call it, then it's going to be a lot quicker and easier for people to do that.
And it's probably not going to be the same template that you would get in an architecture decision record and businesses, it depends, of course, they're going to have to work out what they need in there. But the very basic structure of the options and what's important and the decision that was made and why will go a long way to helping businesses to function a lot better.
Thomas Betts: Well, I think that pretty much covers this full circle of different things that architects need to consider when they're trying to communicate with different stakeholders, communicating with business, communicating with technical people. So Jacqui, thanks again for joining me today.
Jacqui Read: Thank you for having me on. It's been great.
Thomas Betts: And listeners, we hope you'll join us again soon for another episode of the InfoQ Podcast.
