#170 - Essential Communication Patterns for Developers and Technical Leaders - Jacqui Read

[00:01:11] Introduction

Henry Suryawirawan: Hello. Welcome to the Tech Lead Journal podcast. Today I have with me Jacqui Read. So she’s the author of Communication Patterns. So Jacqui, looking forward for our conversation, because I think communication is one of the core skills for not just engineers but also all the technical people working in the tech industry. So welcome to the show.

Jacqui Read: Thank you very much, and hello to everyone listening. Thank you for having me on the Tech Lead Journal. It’s a pleasure to be here. Great to be part of something with so many great guests with lots of useful and interesting things to say.

[00:01:40] Career Journey

Henry Suryawirawan: So Jacqui, I always love to maybe ask from you first to share anything from your career. Maybe any kind of highlights or turning points that you think we all can learn from you.

Jacqui Read: Well, I came from a .NET development background, originally. And I think one of the turning points for me is when I moved into software architecture. That was the thing that propelled me into the architecture space. And then I entered a competition that O’Reilly run, a software architecture kata, which they run a couple of times a year. And since I led a team to win that in 2021, I’ve done quite a lot of work with O’Reilly. So I’ve written my book Communication Patterns. And I’ve started my own consultancy as well. So I provide architecture, consultancy and training, along with speaking and running workshops at international conferences. And so that move into architecture really pushed me into these more interesting spaces, really.

[00:03:17] Architecture Kata

Henry Suryawirawan: Wow. So if you don’t mind, so tell us a little bit more about this architecture kata. Sounds really interesting for those of us who probably haven’t heard about it before.

Jacqui Read: Okay, so the idea of an architecture kata is that as architects, we don’t really get the chance to architect that many systems. And so it’s a practice. So the word kata comes from the sort of martial arts where a kata is a sequence of moves that you go through and you practice those. And so these started with the O’Reilly conferences. They started running these katas actually in-person as short evening events. And then they started, when the pandemic hit, they started doing them online. And they now run them about once or twice a year. So anyone who subscribes to their online training system so they don’t just get books, they’ve got all the live trainings which I do as well. But the kata is a part of that.

And so anyone can enter it and you can form a team just with random other people, which is what I did. Or you can bring a team along and you get a problem which you can solve. And they try to get a real life problem from a non-profit, that kind of thing. And so you can actually solve these problems and create a repository of your design. And since I won it, I’ve actually been a judge on it, which is a really good, really interesting thing to do. So I do that normally about twice a year at the moment.

Henry Suryawirawan: That sounds really cool. So I hope for people who love doing architecture. I’m sure it’s not just about monolith versus microservices, I hope. But yeah, for those you who interested, maybe, yeah, maybe you can also join this, architecture kata. It’s twice a year.

[00:05:03] Writing Communication Patterns

Henry Suryawirawan: So Jacqui, the book that you just published quite recent is called Communication Patterns. So it’s a little bit different than the architecture thing that you’re doing. In the first place, maybe if you can elaborate the background story, right? Why do you come up with this book?

Jacqui Read: Well, I was kind of pushed to think about writing a book once I won that competition. Cause I thought, well, I looked at all the other books that the people were writing and I thought, oh, I could do that. I kind of came to the realization through winning that I did have some useful knowledge and things and useful skills. So I thought what is really missing at the moment? And communication is kind of a big thing. It’s part of the soft skills which people tend to forget about, because they’re so pushed to focus on their technical skills, cause that’s really their day job.

And so I kind of realized that I had a lot of techniques and principles that I was applying, which either naturally or because I’ve learned it from other areas outside of technology, because I have lots of different interests. And so pulling these all together, I realized that I had a lot of things that could be summarized as patterns or antipatterns, which are things that developers and architects and other technical people can understand, because we use them in code. And so I proposed this to O’Reilly and they were really interested in it. And we aimed the book at developers and architects primarily, but it’s got plenty of usable techniques and patterns for other people who are working in tech.

And in fact, one of the people who wrote some praise for it, Rebecca Parsons, let me get this correct. She said, “Anyone particularly in a leadership position should read this book to become more effective.” So in her mind, anybody working sort of in technology really, could benefit from the book. But my hope is that it will get technical people who otherwise wouldn’t prioritize their soft skills to look into it a bit more, because it’s very important when they’re boosting their career.

Henry Suryawirawan: Yeah. So in preparation of this conversation, right, I actually read some parts of the book. I fully agree that this is not just for engineers or those architects, right? So it can apply to everyone, not just in tech, actually. So some of the coverage is also about general leadership principles, ways of working, and things like that. So I think I fully agree that this book can apply to any kind of roles.

[00:07:33] Importance of Soft Skills

Henry Suryawirawan: And I was intrigued when you mentioned that many tech people actually don’t focus or don’t try to improve their soft skills. Maybe in your view, why is that a challenge for tech people?

Jacqui Read: I think one of the main things is that if people have any kind of learning budget at all, whether they don’t get to go to many conferences, they probably don’t get to go on many courses at all. And so they feel pressured really into looking at the technical skills. And probably their managers are probably expecting them to be doing a course on Kubernetes rather than a course on their communication skills. And I think it’s more of people don’t realize that when you are looking at tech skills that, they are key to our jobs.

But if you think about a game of snakes and ladders, the technical skills, they can be ladders, but they can also turn into snakes. If you end up putting a lot of time and effort into a technology that then falls off the hype curve and gets forgotten, you then can’t get the work. You can’t apply to the jobs. But if you put the work into the soft skills, they are always going to be ladders. They’re not going to ever send you down a snake if you are learning these things. So I think that’s the key difference. And a lot of people just don’t realize it.

Henry Suryawirawan: Right. This is the first time I heard about this analogy, you know, the ladder and snakes. So I fully agree again. The communication skills, the soft skills part could actually propel someone’s career and also the effectiveness or impact in their day-to-day job. Again, a very interesting analogy, ladder and snakes. For people who still think soft skill is just, you know, like wishy-washy kind of a skillset, right? So I think, please check out this conversation later so that you can also improve your communication skills.

[00:09:24] Visual Communication

Henry Suryawirawan: So in your book, you cover communication patterns into four different areas. So the first one is about visual communication. So this is probably something about turning, you know, architecture maybe into charts or diagrams or maybe PowerPoint slides. So maybe tell us a little bit more about this area of visual communication.

Jacqui Read: Yes, so I think visual is probably one of the most important areas really to look at, because visuals are what your audience spend a lot of time looking at. And they might be the only thing that they actually look at closely. And so they’re a great way to communicate your concepts and ideas. And they’re usually much easier to understand than text, because they are an abstraction of what could be a complete wall of text if you didn’t do it visually. So they’re a very important aspect and that’s why I started the book with the visuals. And it’s actually kind of where the book grew from originally. I started with that concept and then grew it into all the communication.

So I start with some of the foundational visual concepts, which is where any reader should make sure that they consistently are doing these things before they try out any of the other patterns and antipatterns. And I split all of these out into various patterns and tell people sort of things to look out for, things to apply.

And one of those is called ‘know your audience’. And this is one that people tend to think that they already know about. But it’s not really just what your audience wants from you, but it’s also what you want from your audience. And there’s a few different questions in there you can ask yourself, but one of them, the most important I think, is what do you want from your audience?

And if you are carefully thinking about your audience’s knowledge, you can create a diagram that is what they want. But you also need to get back from them what you need. So maybe you need them to make a decision or they need to come up with some ideas based on what you are giving them. And if you don’t give them what they need to do that, then you won’t get what you want from them. So it’s one of those big, sort of cyclical questions. What do they want from me? What do I want from them? And that know your audience can be a lot more complex than people think. So there’s a whole pattern on that in there.

Henry Suryawirawan: Wow, it’s a great reminder, right? So it’s not just what we want from the diagram, right? So also like what we want from them, right? So it could be, you know, something about making decision or even understanding what kind of solutions that we’re building. So I think that’s really key, because a lot of people just build diagrams. I don’t know, just to tick the box, I would say.

[00:12:12] Visual Communication Essentials

Henry Suryawirawan: And I think one thing as well, when you draw a diagram, very little standard is there. Maybe previously, maybe during my days, there is this UML, right? It was kind of like widely used. But these days I think the standard has been missing. So what is your view about for people to actually come up with a good kind of a set of architecture diagram, probably of some kind of diagram, to explain technical solutions.

Jacqui Read: I think that it’s not particularly important that people choose a particular standard, but that they standardize what they’re creating. Because if you have lots of different types of diagram and they all use different colors, different keys, different symbols, and things like that, it’s very difficult for people to switch from one diagram to another. Because they have to change their mental models of what they’re seeing. And one of the big things that’s important with communication is making things as easy to understand as possible from your audience’s point of view. So I don’t say to people, you have to use UML. You have to use a C4 model. You should be using something that’s standard.

And one part of that is thinking about making it accessible for everyone. So you can think about your colors, making them okay for people who are colorblind, and things like that. There’s lots of different accessibility things that I’ve put. In fact, it’s got a whole chapter on accessibility in just the visuals alone. So there’s an awful lot you can do. But when you are creating your diagrams, you should be thinking about not mixing levels of abstraction, just like when that’s done in code, you get an unmaintainable and confusing mess. And the same’s true for diagrams. If you separate out into layers, so you might have that your context, a conceptual, logical and physical, that kind of thing. Or if you’re using C4 models, you probably have your context, your container, component, and code. Although component and code, they’re less useful. But the top two are very useful. And once you separate these out, that means your audience can more easily understand what they’re looking at. Which is really your main goal when you are communicating with different people.

So when you are creating your diagrams and making them consistent, you can also use another pattern in there, which I call representational consistency. And that’s how you make sure that there are explicit links between your diagrams. So part of that is using consistent keys and colors and things like that. If you are using different notations like UML or a data flow diagram, you are going to have different shapes. But you need to be consistent in how you are presenting things and how you are referring to different things in your text. And the colors you are using and things like that. But when you are separating things out into the different levels of abstraction, you’re gonna end up with more than one diagram, which is really good for getting people to understand what’s in it because there’s less in it. And different diagrams are gonna be for different audiences as well.

But you need to make sure that your audience can navigate between those diagrams and see how they fit together. And there’s lots of ways you can do that. One of those is when you use identifiers in each diagram. So if you’ve ever used a data flow diagram, it has processes which are numbered, and data stores typically have a letter identifier for them. So if you are using different levels of data flow, if you are moving down and breaking things down. Each of your diagrams should have the same identifiers on it for the different data stores if they appear in more than one diagram. But also if you’ve got a process that’s labeled number two in one diagram, then when you break that down into another diagram, you can label it 2.1, 2.2, 2.3, etc. And so you are just creating that link between them, making it easier for people to understand.

Henry Suryawirawan: Speaking about consistency, you know, color accessibility, right? When I read your book, I must realize that I’ve never cared about those things before. But now that you mentioned in your book, right? So I think it’s really important, especially maybe for different kind of audience, right? We sometimes just pick the color that we think are nice. But in your book you cover there are different kind of a gradient or maybe that kind of color that you should choose instead. Use the consistent theme, right? I think you mentioned about consistency so many times. Not just color, but also shapes.

And I think very, very important is about the mixing level of abstraction, right? So I think when we draw diagrams, sometimes we don’t use the same kind of abstraction. Sometimes you could be in a context. But sometimes you go down into more like a physical deployment sometimes, right? And you put it all together in one diagram. So I think I like the C4 model from Simon Brown. So when I read his book also, he covers from his audience, right? There are so many different types of diagrams and it’s very, very confusing, because they all look different. That’s the first thing.

And the second thing is the levels of abstraction. Usually it’s mixed, jumbled up together. So I think it makes it really hard unless you follow how the author is creating the diagram, right? So for people who just saw the diagram first time, I’m sure they’ll be confused. So I think very, very important about this.

[00:17:46] Visual Narrative

Henry Suryawirawan: And I think another thing you cover in your book about this visual communication is about the narrative. Maybe how you present about the diagram, right? So tell us more about how can you narrate your kind of visual better.

Jacqui Read: Well, narrative is actually very important factor when it comes to communication as a whole. So when you’re thinking about when you are telling a story or when you are writing something or when you are creating a diagram. And one of the main reason for this is that we evolved listening to stories and passing information on in stories. Because we could speak and use language before we could write anything down. And so our brains are kind of tuned into stories. And so narrative is very useful when you are trying to get somebody to understand something.

But it’s also really useful in diagrams as well. And the main way that you can apply this to diagrams is when you’ve got those various different diagrams, as I said before, you’re going to have these different kind of levels of abstraction. And when you are talking to people about things, you need to order them from sort of the high level down to the low level. And the pattern, I call this “the big picture comes first”. So we often forget that others don’t have the same understanding as us, and we need to give them that opportunity to learn and take that important higher level information and fill in any holes before we dive into what we really want to communicate to them.

So maybe you are talking about how you are specifically gonna handle a small process down. You really want to get to this low level data flow diagram that you’ve got. But you need to consider what information your audience needs first and maybe start all the way up at a context diagram to give people an idea of what other systems you’re talking to, because that’s important information when you get down to that.

And so you probably need to actually go through several different diagrams or slides or just giving people other information. Like it might be the constraints for the system that are important to what you are going to be talking about. And so it’s important to start at that high level and go lower. Because if you start right at the bottom, you are gonna get lots of questions and people won’t understand what’s going on. They’ll probably also be quite bored as well, because if you dive straight into the details, that’s quite boring. So give them that big picture first. And then get down to that point so that everybody’s got the information you need.

Henry Suryawirawan: Yeah, so I find this different level of views, right? So it’s really important depending on your audience which you mentioned in the beginning, right? So understand the audience and present them with the kind of view that is suitable for them. It’s not like, for example, if you’re talking to stakeholders, maybe don’t show directly to the component or code level, because most likely they’ll feel lost. And it’s very, very important to actually know the audience and present them with the view that you want and narrate that such that people can understand.

So thank you so much for covering this visual. Maybe just a little bit of recap, right? The first thing is about knowing your audience. Don’t mix levels of abstraction. Be consistent in representing the things in your diagram, be it color, notations, and things like that. And when you narrate, big picture comes first. So I think that’s really key for people who want to find out more patterns about visual. Go check out the book.

[00:21:09] Multimodal Communication

Henry Suryawirawan: So let’s move to the second section of your communication pattern, which is about multimodal communication. Essentially things like written, verbal, and non-verbal communications. So maybe tell us why this is important for engineers and architects.

Jacqui Read: Yes, so I called it multimodal so that I could sort of give it a bit of an umbrella term for written, verbal, and nonverbal. And these are skills that we quite often forget that we use on a day-to-day basis. Even if we’re not working in an office, we are still using verbal and nonverbal skills and techniques, when we’re on a call with people with video or not. And so this area is quite important really. And I started off with the written area. And there’s quite a few different patterns and antipatterns in that one.

One of the simplest things that people can apply, has “simple” in its name as well, and that’s using simple language, and it makes it much easier for people to understand if you use a simple vocabulary compared to sort of more terms that aren’t used very much. And it helps everyone, but it’s especially good for those for whom the language that you are using is not their native language. And you are also being more inclusive to people who have dyslexia or things like autism or ADHD as well. Cause you are making it more understandable for everyone. So a couple of easy examples. If you can use the word “buy” rather than “acquire”, and you can use the word “most” rather than the phrase “a majority of”. And it just makes it so much easier for people to understand. But also if you are using less words as well, it means people can read it quicker. And so people are much more likely to be quite happy with that.

And also with the writing aspect, I look at how you can structure your technical writing. And one of the principles I’ve pulled in from other areas is the Minto Pyramid principle. And there’s a whole book and loads of training and stuff on that by Barbara Minto if you are interested in that. And it’s all about using structure to make a point. And then once you’ve made that point, you then back it up. So you are making sure that most important information comes first. And it can be applied to documentation, but also it can just be applied to your emails and messages every day.

And you might actually see people applying that sort of thing on their social media messages. So that first sentence catches your attention. Cause quite often it’s the only bit you can see unless you click “show more”. So it’s getting people’s attention, but it’s also giving them that most important information first. And news articles are written in that way. You’ve got the headline, the most important information and then you get the next most important information. And so at any point you can stop, but you’ve already seen the most important information in that.

And you can apply that very easily. It’s really useful in emails and things. How often have you read an email where it’s kind of rambling on about different things, and eventually, you find the bit that you really need to do something about, and it’s hidden down in there. And if you hadn’t read it properly, you wouldn’t have been able to find that. And so if it had just started with that most important piece and then given some explanation, then that would’ve be much easier for you. And so it’s just thinking about, again, making things easy for people to consume and understand.

Henry Suryawirawan: So thanks for explaining some of this, right? So I recently read a book as well. I think it’s called “Writing for Busy Reader” or something like that. I think some of the key points mentioned in the book also covered by you just now, right? So first, use simple language. Less is better, right? So don’t write in a more elaborate and long sentence, right? So if you write it shorter, people will be able to read it faster, and they will make sure to read it in full as well, right? Because if it’s too long, right, sometimes people just scan through and maybe skip or archive your email, right?

And the Minto pyramid, I think it’s also very, very insightful for some people who never learn about writing before, right? It seems counterintuitive in the first time, but actually, if you learn about it, right, I think it will make your writing communication much more effective. You know, some people also call this technique something like TLDR, right? So what’s your “too long; didn’t read” kind of a message, right? Your key message. Some people call it BLUF, right? Bottom line upfront. I think it’s used in military. So, I think it’s the same key message, right? Your headline first, the most important thing first before you actually kind of like cover your rationale.

I think in Minto pyramid as well, you kind of like break down your main topics into like at max three, I think the recommendation. And you start building a tree, like a chain thought of reasoning. So I think people should read about this technique. And this Minto pyramid also used, I think, from McKinsey, right? And they kind of like mandate that for all the consultants to use this kind of technique.

Jacqui Read: Yeah, I think she developed it when she was working at McKinsey.

Henry Suryawirawan: Yeah. So I think for people who have not heard about this technique before, do check it out because I think it’ll make your writing slightly more effective if it’s the first time, right? But if you consistently use it, I think it’ll make it even more effective.

[00:26:29] Verbal & Non-Verbal Communication

Henry Suryawirawan: So moving to maybe the verbal communication aspect. I think most engineers prefer chat rather than talking in person, right? But what is the key message that you want to cover in this, about verbal communication?

Jacqui Read: Yes. So as well as the written, I cover the verbal and the nonverbal. And I think people sometimes think of the verbal, but the nonverbal is something that we think about less. And so we use this all the time in person or remotely. And a lot of what we get from a conversation, we actually pick up really simply and quickly. There’s the system 1 and system 2, which was written about by Daniel Kahneman. And with the system 1 makes a lot of decisions really quickly, really snappily. And a lot of that we like from people’s facial expressions and things like that. And when I’ve written this, I’ve structured it as I’ve written with the patterns and antipatterns to help technical people.

I’ve also structured this around encoding and decoding messages, which is something we are all kind of familiar with software development, and we don’t really think about it in real life. So when we’re setting up communication between services and different parts of the code or APIs, we encode what we are communicating and we also decode any replies. So it might be using HTTPS or message queues. But we’re doing a translation each way. And we don’t really think about when we are talking to someone else, even if you are speaking the same native language. Everyone’s an individual with different backgrounds. And so we are constantly encoding and decoding. And things can get easily lost or misunderstood.

And so I talk about some different cognitive biases and also body language. And it’s based on the fact that if you think about these things, then you can think about encoding them yourself to actually give other people the correct message, the message you want them to receive. But you can also work out better how to decode things that other people are saying, so you can realize that they’re actually thinking possibly something different to what they’re saying and that you can start to try and dig deep into that. And so by reading this section, you can improve the accuracy of your own encoding and decoding. And take all these things sort of use them to your advantage rather than just being completely oblivious to them, which quite a few people are.

Henry Suryawirawan: Yeah, software developer, I think, we are all used to, you know, this encoding, decoding, right? Be it, you know, you’re calling APIs, you use some kind of interface contract between two different protocols, right? So I think we are so used to it, but in the communication, maybe it’s written, verbal, or whatever that is, right? We don’t actually think about it. And I think these days, we all work in a pretty global setup where people have different culture, different language, different interpretation of stuff. Even some culture actually might take a certain word differently than other culture, right? So I think it’s really important that we use the right encoding and also for you to do the right decoding. Because sometimes there might be a misunderstanding happening if you don’t use the same protocol or the same contract, right?

[00:29:58] Encoding & Decoding

Henry Suryawirawan: Sometimes being explicit, like when you mention about something, right? Just explain what you actually mean exactly. By using that term, I think it’s really important as well. In your view, right, in this global remote setup these days, how can people become more aware or conscious about this encoding, decoding process?

Jacqui Read: Yeah. Well, I think as you said, a lot of people are much more likely to type a quick message than they are to either call someone or pick up a phone these days. And one problem with text is that you can’t get this body language. The tone of voice, you can’t get all those things in there, which you do even if you’re just talking on the phone, you get something from that. Even if it’s not face to face or on a video call. And even if you are on a video call, it’s actually a lot harder to decode things from somebody on a video than it is in real life. And so when we are using all these remote forms of communication, we are making it a lot harder for ourselves having to work a lot harder to understand each other.

And so knowing about these different things to do with body language and how you can encode things a bit better is very useful. So applying the writing, just the pyramid principle that really helps people. And if you are reducing the amount of effort that people need to use to understand you, then people are much more likely to come round to your way of thinking. Because you’ve given them something really easily, whereas they might have to work a lot harder with someone else.

Henry Suryawirawan: Yeah. I find when you interact with someone through chats, right? Sometimes, yeah. Like what you said, the emotion is not there. Sometimes we actually fill in the emotion by ourselves, our own perception of maybe this person is angry, this person is frustrated, right? But it may not be true from the person’s perspective itself, that actually they’re frustrated. So I think it’s very important not to judge quickly, right? Or sometimes just clarify with the person before you actually make assumption. And maybe use a lot more emojis, right? I think you mentioned it in your book to actually convey some emotion in your message. Use some more emojis, although emoji can be interpreted differently as well in some different culture. So thanks for covering that.

[00:32:22] Communicating Knowledge

Henry Suryawirawan: Let’s move on to the next section which is talking about communicating knowledge. So this is something maybe about coming up with wiki or sharing documentations, which I think many engineers know it’s important, but somehow still many of us don’t get it right. So tell us how can we upskill our communicating knowledge kind of skillset.

Jacqui Read: Yes. So this is all about knowledge rather than just documentation. Because documentation is a very small part of knowledge. And I know that a lot of people are turned off by the word documentation, they don’t want to have to create that. But despite its worth, knowledge is often neglected in organizations. It’s not part of people’s day-to-day job. They’re not rewarded for sharing knowledge and code is often given a lot higher priority than data. So people are very insistent that you use version and control for your code. But when they’re thinking about data, that’s often like backups for it, and often an afterthought. Despite the fact that data is often a lot harder and sometimes impossible to replace. Whereas you can rewrite some code, but your data will be lost.

So knowledge is really important, but just like data, not given enough information. Not given enough thought in a lot of organizations. But documentation and knowledge management, they give so many benefits when they’re done well, if you just think about all the time that’s wasted by people trying to find communication. I think it was a Forrester study that said that knowledge workers spend 30% of their time looking for information. And that’s what we are. We’re knowledge workers. And what would your boss say if you said, oh, actually I spend 1.5 days per week looking for the information I need? I don’t think they’d be particularly happy about that. So that’s why I’ve dedicated a whole part of this book to knowledge and how we can improve our use of it. Because there are so many benefits to the way people work and the end results for products and for customers and all these other things as well.

And so I cover some principles of knowledge management, and that includes one that I call perspective-driven documentation. And this is my own principle and practice that I have come up with, with all the research that I’ve done on this. And it puts the focus on who you are communicating with and also why you are communicating with them. Because when you are thinking about your audience, you are not just thinking about who’s looking at a particular piece of information. You are communicating with them for a reason. Maybe it’s because they’ve asked for that information, or maybe it’s because they really need that information, even if they haven’t asked for it.

Basically, you need to determine what should be communicated by thinking about who you’re communicating to and why, and rather than the other way around. Quite often people, as you said, it’s a bit of a tick box exercise like, oh yes, I’ve created a context diagram. I’ve created the constraints documentation for this. But you really need to think about why and who you’re talking to, and then that will help you work out what you need to do. And if you come at it from that point of view, then you’ll probably not waste time creating things that actually people didn’t need in the first place. And so stakeholders need to be able to find and understand that information they need when they need it.

And many people are gonna be in one of two situations. Either all of their information is in some sort of bloated huge word processing document or similar. And it’s difficult to find what you need and it’s difficult to version that whole huge horrible Word document. Or it’s spread across many, many applications and different teams are using different knowledge repositories. And some people have got it in a wiki, other people have got it in something like Confluence or Notion. And you inevitably end up with old data lost in sort of various legacy applications that no one wants to use anymore. And we thought we’d migrated from them, but we haven’t. And so of course, there’s gonna be information locked away in people’s heads and also their personal notes.

And so when you look at this perspective-driven documentation, it organizes that information into what I call perspectives. You could also call them views, but that’s a very overloaded word in technology. And each of these perspectives addresses the needs of a particular stakeholder. And so items within that perspective can be reused in other perspectives. So that might be a diagram appears in more than one of these perspectives, cause more than one stakeholder is interested in it. It’s a little bit like reusing code so you can follow the DRY principle with it. Don’t repeat yourself. And it makes things easier to maintain. And I found it actually also goes really well with domain-driven design if you are doing that.

But when you create these perspectives, you can reuse things. So you might create it as different wiki pages and then you embed a diagram into each of those wiki pages. But when you are doing that, one thing to think about with this DRY principle is that sometimes you don’t want things to always be the same. So maybe you are referencing a particular law or a standard that’s applicable at the time. And if you just link to that, or if you always keep that as the most updated version of that standard, then it won’t make sense. If you look back at that, and people say to you, oh, why didn’t you follow that bit of the standard? You would have to work out that it didn’t exist at the time you did this part of the project. But if you keep it as this is the version of it as it was in January 2024 or whatever, then you can see that, oh, things have changed now and so we need to make some changes.

But it’s all about sort of creating these perspectives for people, for particular stakeholders and therefore not creating stuff that people don’t actually want and wasting your time. And that’s probably one of the main benefits of this way. Not wasting your time on things and giving people what they actually need.

Henry Suryawirawan: Yeah. Sometimes what I can see in practice, okay, there are a few things that I see in practice. The first thing is we all love to communicate through chats these days and put a lot of information, maybe sometimes meeting notes, maybe things that we discuss and everything’s over chat. Mostly Slack or Teams, right? And we never take the time to actually put it somewhere in a repository, be it wiki or maybe some centralized place. And we just assume that everything can be searched on chat. But chat I think is a semi-structure communication channels. So sometimes things are not so easy to find as well. And especially if you have multiple threads, you know, discussing the same thing. So probably that is one experience that I have.

The second thing is about what you mentioned, right? People seem to value code much more than the knowledge or the data, right? And they push engineer to always start with coding. You know, start with coding as soon as possible. But sometimes, for example, things like requirements or maybe even like drawing some kind of design diagram or system design diagram, is something that sometimes get neglected and people prefer to jump straight to the code.

And I think the third thing like you mentioned, right, perspective-driven documentation. Sometimes we just write documentation for the sake of ticking the box without actually knowing who will actually read the documentation. So I think those three aspects are things that I normally see in my career as well.

[00:40:14] Tips for Capturing Knowledge

Henry Suryawirawan: So for people to start thinking about coming up with a good way of capturing knowledge. Any kind of tips and tricks for developers to do things better on this area?

Jacqui Read: I think as you just mentioned about there being knowledge in chats and emails and things, I think that’s possibly one of the worst situations you can have when all the knowledge is locked away in places other people can’t find it. So I once heard someone talking about they were saying, oh, yes. Or whenever I want the answer to a question, I just search in Slack. And quite often someone’s already asked it. And that filled me a dread, cause I thought, well, if someone needs that information, do they know it’s in Slack? Do they have access to the Slack channels that it’s in? And when does that information get archived or possibly deleted by the products you’re using? And if you’re doing that same thing with email, giving people information over email, then only the people whoever receive that email will get it forwarded to them ever have that knowledge. And quite often your organization will be archiving or deleting email that’s maybe over a year old or something like that, and maybe you don’t even know that. And so all that knowledge then gets lost, especially if those people who wrote it then leave the company.

And so one big tip that I have is when you are sharing knowledge, if people ask a question on a message or over email, don’t share the knowledge, share a link to the knowledge. Because then people will know where to find it. If it doesn’t exist in your wiki or whatever you’re using, then create it and share the link. If you look at it and you realize it’s out of date, then you can update it and share the link. I mean, you might have to get together to work out how to update it. But yeah, that’s really important for all of your knowledge. But if you just think about sharing this link, that will help you to keep all your knowledge in a place that is accessible to everyone and not spread across all these many, many apps that people don’t know where it is and they probably don’t have permission to access it anyway. So that’s my big tip there. Share a link rather than the knowledge itself.

Henry Suryawirawan: Yeah, I think it’s a great tips, right? Because sometimes we actually want to answer quick, right? Maybe because of busy or whatever, right? We want to answer very quick and we just dump the knowledge and the content in the chat itself. But I think the tip is really, really useful, right? So provide a link, take your time, put it in the wiki. It takes a village to actually do this kind of discipline. It should not be just one person doing it all the time, right? It takes a village. Everyone should be conscious about doing this. So I think sooner than later your knowledge management will become much richer and people will be able to find knowledge much more often.

[00:43:05] Get Feedback Early & Just-in-Time

Henry Suryawirawan: Another thing that I find really useful in your book, you cover in this area, is about getting feedback early and often. And also just-in-time architecture, right? So I think sometimes when developers are being tasked to create documentation, we kind of like take the whole week or few days to actually write a long document before we share it to other people. I think it’s worth to mention about these two aspects, so that engineers maybe can get feedback early. And also just write whatever that is necessary at that point in time. So maybe if you can cover a little bit on this.

Jacqui Read: Yeah. So with knowledge, as I said, it’s not just about managing documentation. And it’s not about just what knowledge management system you use, it’s actually sociotechnical. And so you have to take into account people for it to be successful. And a simple way to improve your knowledge and documentation, as you say, is to get feedback early and often. And it really helps you to not go too far down the wrong path without being able to course correct. So don’t wait days or weeks to ask a colleague or a stakeholder for feedback on the artifact you’re creating, whether that’s something written or a diagram.

And don’t spend more than a few hours on something big or even a shorter time on something smaller before you get feedback. Because if there’s something that you didn’t know, that means that you are going to waste a lot of time on that. You want to get that feedback early. So we all know that when we get given requirements that they’re not gonna be complete or they’re going to be incorrect. And so if you work for a long time designing something based on those requirements, then take it to your stakeholders and they tell you that something was missing or something’s wrong. You’ve spent a lot of wasted time and effort on that. And so get that feedback really, really as quickly as you can.

And it might be something fairly informal if you’re in an office. Just asking someone who’s sitting next to you to have a quick look. Or it might be actually setting up just a brief 15 minute conversation with someone, a video chat just to show them. It doesn’t have to be a big like, oh, three hour meeting. We need to have a look at what I’ve done so far, because you haven’t even spent three hours on it. But it’s just getting that feedback quickly so that if you think about Agile, this is what we’re trying to do. We’re trying to get quick feedback loops. And I think even if people are managing to do that with the code that they’re putting into the system, get it to the customer early, get feedback quickly, they forget about this. And they apply that same principle to all the work they’re doing. And it will help you in that.

And then this also compliments another pattern which I talk about, which you mentioned, which is just-in-time architecture. And it’s important not to make a decision earlier than the, what I call, the last responsible moment. And that means that making the decision too early can mean having to change that decision when you get new information, which comes to light. And if you change your decision, that’s often expensive thing to do, either moneywise or effort and timewise, and therefore that costs money anyway. And especially, if they’re architectural decisions, they tend to be more expensive to change. And if you have to change that one decision, what about all the other decisions that you made based on the outcome of that decision? You probably got to change all those as well.

And so you can get this awful chain reaction, because you’ve made a decision too early. So even if you’ve got someone kind of breathing down your neck asking for a particular artifact or a particular decision, you really need to try and put them off until that last responsible moment and you create your artifacts just-in-time. If people really are insisting, then you can create something, and just say, I put something on it like a disclaimer that this is a draft. If you base anything on this, it may need to change. And that can help to communicate why you can’t just make this decision now or create this artifact right now. And in the end, it’s going to save you time and money.

But one of the other really good things about this is that it means you can focus on what really needs to be done now instead of having all your time blocked out working on things that aren’t needed yet. Because we all get unexpected work. This inevitably comes our way all the time. Things go wrong or something pops up. And if you’ve got your time blocked out working on stuff that isn’t needed right now, you don’t have that slack to take on that inevitable, unexpected work. So doing this just-in-time architecture means that you have that time to work on the unexpected. You don’t waste time on decisions that shouldn’t have been made at that point. And you just get a much more agile process to your working as well.

Henry Suryawirawan: Yeah, I would recommend people who probably do a lot of documentation to think about these two aspects really, really closer to your heart, right? Because sometimes I see so many engineers, spend many, many days to come up with documentations, which actually in the end, right, sometimes they need to do a rework or it just doesn’t solve the kind of problem that they’re trying to solve by coming up with the documentation. So get feedback early. And sometimes I think in your book you mentioned about templates, right? You can actually also come up with templates so that people are guided on what aspects to fill in in the documentation rather than always having to come up with a different kind of a format all the time. So I think for people, please bear these two key points so that you can communicate your knowledge much better.

[00:48:59] Communicating Remotely

Henry Suryawirawan: So the last aspect is about communicating remotely. So probably if we know about this remote work, right? There are always two things that are always mentioned. Synchronous and asynchronous. Meetings, no meetings. Deep work and things like that. So maybe a little bit of advice here for people who are more used to this kind of remote setup now or also hybrid kind of a work setup.

Jacqui Read: Yes. A lot of us are either working remotely or in a hybrid. Or even if you are working in an office, you are probably working with other people who are working remotely and hybrid. Or maybe you are working with people who are in an office in another country. Even other time zones, of course. And so there’s an awful lot to take into account when we think about how we’re communicating with people. And a lot of people kind of think they feel a bit sort of professional at this now, cause we’ve been doing it for quite a while. But it’s not really quite as simple as people think.

If you consider how many companies at the moment, even ones who actually make remote communication tools, they’re trying to get their employees to come back into the office for more of the time. And yet you’ve got other companies who are thriving as sort of fully distributed or hybrid organizations. And it’s the fact that the way in which things are communicated seriously affect people’s understanding and their productivity. And people need to understand a lot to decide whether a communication method should be either synchronous, which is in real time like a meeting, or asynchronous where the recipients read and respond on their own timetable. In fact, a podcast is also an asynchronous method of communication. So you are experiencing that right now.

But many people don’t realize how disruptive synchronous communication can be to people’s work. So working out which communication should be async is vital. People getting their best work done. So for example, synchronous activities, things that work pretty well synchronously are things like generating ideas or building rapport like team building or maybe a project kickoff. That can be good for a synchronous meeting. With asynchronous, things like reporting progress or gathering feedback. So using things like comments on documents or architecture decision records or other forms of decision records, those can be done asynchronously. And often communication should actually be split between the two. Some people like to evangelize asynchronous communication, but really some things are better done synchronously.

And one of the things I talk about in the book is an asynchronous sandwich. And that’s where you are maximizing your synchronous time. So if you are getting everyone together for an hour synchronously, then you want that hour to be all activities that are best done synchronously. So any part of that that is best done asynchronously before or after, you want to split off from that so that you are not wasting people’s time. If you have to get everyone together for two hours, that really knocks everybody’s productivity. And probably, not everybody needs to be there for those two hours.

And that’s one of the things that people really hate about meetings, especially remote meetings, because they’re even harder to concentrate in. I said earlier about it’s much more difficult to read people’s verbal and body language and so you are already putting more stress on people. So making that synchronous activity just for the stuff that works well synchronously is going to be really useful for that.

Henry Suryawirawan: Yeah, sometimes I think it’s very tricky, right? Some people is more towards asynchronous. Like I would prefer asynchronous all the time. Or some people, like for those who come back to office, are forced to come back to office, maybe the management or leadership likes to be in sync all the time. So I think always there are polarizing thoughts, but I think your book kind of like give a good guidance. Like, for example, you probably need to do meetings in-person synchronously if you want to get like some kind of consensus, you know, like kickoff, idea generation, right, rather than asynchronously. And async is more towards thinking, you know, like getting comments, feedback, ideas.

And I think I also like one of the thought from James Stanier about asynchronous versus synchronous. I think he mentioned about if you want to get a strong consistency, do it synchronously. But if you think you can do like an eventual consistency kind of manner, do it in asynchronous way.

And I think in your book, you also mentioned one anti-pattern that I see happen all the time. We try to do async, meaning like using chat, but actually we kind of like reply back and forth synchronously in real time in the chat. And we make decision very, very quickly on that chat as well. So I think this probably is an anti-pattern, because there are some people who are not in the conversation itself. And also it’s a lot of back and forth means probably the ideas need to be talked through much better rather than in chat, right? So for people, probably if you’re frustrated with some of your asynchronous or synchronous kind of communication, do check out Jacqui’s book on this aspect. So I think you’ll get a lot of more tips on how you can improve on this.

[00:54:23] 3 Tech Lead Wisdom

Henry Suryawirawan: So Jacqui, it’s been a great conversation. Unfortunately, we have to wrap up pretty soon. I have one last question which I normally ask for all my guests. I call this the three technical leadership wisdom. You can think of it just like advice for all of us to learn from you. So is there something that you can share with us about three technical leadership wisdom?

Jacqui Read: Yes, I had a good think about this. And the first one I want to share of the three is that soft skills are pretty much always going to be those ladders for you to climb in your career, whereas your tech skills can turn into snakes, meaning you’ve got to start again with another skill. So emphasizing that from before.

The second thing that I’d like to share is that there are always trade offs with anything in technology. Probably, pretty much area in life, there’s always going to be trade offs. There’s no silver bullets in technology or architecture or anything really. And you need to understand what’s important to make every decision. It’s not just about what’s the latest technology or anything like that. And so you need to use tools such as architecture decision records to help you with this. And thinking about architecture characteristics, which I also talk about in the book. And that helps you. It gives you this guidance for what’s important for making that decision.

Then my third tip is what we do as technical professionals always involves people. Systems are always sociotechnical. So you cannot ignore the people when you are trying to build or make changes to a software system. And things that are useful to help with this are systems thinking and also techniques like collaborative modeling. Team topologies is an interesting area to look at. And also things in my book, like just-in-time architecture can help you with this sociotechnical element. So those are my top three tips at the moment.

Henry Suryawirawan: Wow! I really love the ladder and snake analogy, so I’ll use it more often. I think you put it very interestingly, right? So communication skills is like a ladder for you to climb to bring you always up, right? Sometimes it could also bring you down if you communicate wrongly, I guess. But yeah, technology always keeps changing, right? So I think it’s like a snake, where you always kind of like have to up to date yourself, right? And also keep following the trend. But I think, yeah, the communication is always applicable in any type of situation, no matter what role or what job that you have.

So Jacqui, if people love this conversation, they wanna reach out to you or ask you anything in person or online, right? Is there a place where they can find you?

Jacqui Read: Yes, the best place to find me is my website, which is jacquiread.com, J-A-C-Q-U-I-R-E-A-D dotcom. And you can also find the book on its website, which is communicationpatternsbook.com. So for everyone who’s interested in this, please reach out to me, especially if you want to look at working together in any of the aspects that I’ve talked about today or in software architecture and sociotechnical areas in general. And thank you very much for having me on Tech Lead Journal.

Henry Suryawirawan: Yeah, so I highly recommend reading Jacqui’s book. Again, communication and soft skills, probably not so many engineers think this is important, right? Rather than, you know, following all this technology. Or maybe AI, ML, now, generative AI, right? So I think communication is still applicable no matter what age, what era you are, right? And there’s always a lot of things that you can improve in terms of communicating better. So thank you for your time today, Jacqui.

Jacqui Read: Brilliant. Thank you.

– End –