Episode 254 - Communication Patterns with Jacqui Read | Transcript

So today’s topic is going to be a communication pattern.

It’s also the title of a book that Jackie wrote.

And actually, she’s going to present at HRMeets Architecture about design patterns for software diagramming, which will take place on April 3rd and 4th, I believe, and your talk is on the 3rd.

It is.

Yeah, and we have a special discount code for that, and I’ve just added it to the chat.

So it’s AMASAIS10.

And that’s pretty much everything.

Oh, one thing.

Originally, Lisa was supposed to do this episode.

Unfortunately, she couldn’t make it, so this is why I took over.

So, Jackie, can you say a few words about yourself, what you do?

I certainly can.

So I originally came from a .NET development background, and then I moved into software architecture.

And I got working with O’Reilly after I won one of their international software architecture cata competitions, and they run those typically once a year.

So if you are a subscriber to O’Reilly, I recommend having a look at those.

And then after that, I proposed this to my book, Communication Patterns to O’Reilly, wrote that for them when they accepted that, and I’ve been teaching with them since then as well.

At the moment, I do a lot of speaking at international conferences.

I run workshops there as well.

I’m running a few workshops at conferences this year and also online.

And I offer things like private training and consultancies to businesses on topics such as software design and communication and other things like that.

So that’s me in a nutshell, really.

Yeah, sounds great.

And you’re located in the UK, right?

Yes.

I actually had a little bit of good weather this week.

It’s been quite nice.

Yeah, it’s overcast here, so yeah.

So what are communication patterns?

That’s a very good question.

So the information in the book is presented as both patterns and anti-patterns, which is probably something a lot of people recognise from code and also a bit from architecture as well.

So the patterns are things that tend to work a lot in a lot of similar situations.

And there’s always going to be exceptions to that, but they tend to work.

Then anti-patterns, they’re things that look like they’re a good solution or kind of might be the default thing that happens when no thought’s put in towards being done.

They tend to have more downsides than upsides in the end.

And so communication patterns and anti-patterns are all to do with different types of communication, such as there’s visual communication in part one of the book, things like diagrams.

Then there’s communicating with people when you’re remote from them, which might be your colleagues or might be your customers.

There’s written communication in there as well.

And also the way we communicate knowledge, which is partly documentation and partly other types of knowledge.

So it’s all split out into the different sections.

But, yeah, those are patterns and anti-patterns.

And I thought there would be a really good way to present it because people generally understand patterns and anti-patterns if they are a coder.

And you can understand what they are, even if you are not a coder.

So is this only – I mean, obviously, this is a stream about software architecture in a way, and also you have a strong background in this regard.

So is this something that is primarily meant to be used for architecture documentation, or is it also useful for other things apart from that?

Oh, it’s useful for lots of things because communication is part of kind of all of our lives and part of our work.

And we constantly communicate.

We speak to people.

We email.

We use instant messages.

We create documentation, as you said.

And so the patterns in the book can apply to kind of your whole working life.

So not just actually communicating the architecture of your software.

It applies to all the documentation, not just the architecture, but also how you work on a day-to-day basis with your colleagues and how you communicate with your customers as well.

There’s a lot in there about even how to use email well because everybody is sort of forced into using email, or most people are.

And if we sort of optimize how we use it, I would recommend to people not to use it for the better option.

But if you have to use it, there are some really good ways in there of helping you to do that.

Okay.

Sounds really interesting.

But I want to dive into that subject a little bit more.

So I’m wondering, with your background in architecture, did that make you write that book?

Or is it something – I mean, is it like you feel that this is in particular useful for architects?

Or is it something – what was the motivation to do that?

Is it something that comes from your architecture background?

I think it’s partly the architecture, but just generally working in software development, I kind of realized that it was something a lot of people struggled with.

Because if you think about the – if we just think about diagrams, think about the diagrams that you see that, of course, other people have made.

Not the ones you made, of course, but diagrams other people have made.

And you just think, I don’t even understand what this means.

Or maybe you think, oh, this is great, but the key information I need isn’t on here.

Or you think, oh, this would be great if I printed it on an A4 piece of paper, but I can’t see it on my screen.

I’ve got to kind of zoom in and things like that.

And so I just kind of realized that there were a lot of things that people struggled with.

And it’s kind of because a lot of people – everyone’s kind of encouraged to learn the technical stuff.

You’re kind of encouraged to learn the Kubernetes stuff, the cloud stuff.

But what really kind of binds it all together is how you communicate with people and how you kind of communicate with customers, but also how you communicate your design or architecture to your development team.

Because if you can’t communicate well, you’re not going to get what the design or architecture says, and you’re going to end up with something that probably goes all the way to production or costs a lot to change again before it gets to production.

And you get all these big problems.

So it’s great that we all know the technical stuff, but we forget about what a lot of people call soft skills, but they’re kind of the hardest skills, aren’t they?

Yeah, and I’m afraid I can’t resist to tell an anecdote that is also related to the stream.

So last year, we decided to do something at Java Forum Stuttgart, which is a purely technical conference.

And at the booth of Socratory, the company that Lisa worked for, we set up a camera so people could give some statement, and also we set up a box so that people could put in a piece of paper.

And we asked people what the most important skill would be in IT.

And it turns out that I think like 50% of the people actually said communication.

So there you go.

And the majority was about social skills like talking to people and these kinds of things.

So I found that pretty interesting.

I didn’t make up my mind beforehand like what a likely outcome would be.

But I mean what you said is so very true that communication is so important, and it seems that people really understand that.

So that’s the point.

Yeah, I thought it was quite interesting.

It’s one of these experiments that we did where I wasn’t sure about the outcome, and actually I didn’t think about the outcome beforehand.

And it provided some interesting insights.

Okay, so there is a question in the chat from Jude Root.

And he says, I suspect it’s a he, I’m afraid that even with own diagrams when they are not regularly maintained, it is a bit like what did I try to put with this approbation box in here five years ago?

Anything you want to say about that, any comments?

Yeah, one of the things I talk about in the book actually is not using an abbreviation unless you put in what it means.

And so one thing that’s missing from a lot of diagrams is a key or a legend.

And so if you are using an abbreviation in your diagram to save space, put in the key or the legend what that means.

Because the problem is an abbreviation can mean lots and lots of different things.

And even if you put that in the text next to your diagram in, say, in a Web page, if that diagram is then shared without that Web page, you then lose that information again.

So, yeah, that’s one of the actual patterns I talk about specifically is abbreviations.

That’s a really good example.

But with the idea of regular maintenance, a lot of diagrams won’t get regularly maintained because you just don’t have the time to do that.

And one of the problems, if you use something that, like, say, UML, it can be useful.

But UML diagrams tend to be very detailed and put a lot of technical information in there.

And so if you end up putting a sequence diagram which has, say, like method calls on it, if you think about it, some people are pushing changes to production multiple times a day.

Those method names could change before you’ve even finished creating the diagram.

So why bother putting that in?

Put it in in kind of very plain language that anybody can understand rather than going into that detail.

And so if you focus more on the high level detail in the diagrams, those diagrams go out of date far less often, whereas the very nitty gritty stuff goes out of date.

And so if you’ll say creating an API, you don’t want your documentation for that API to be kind of manually done.

You need to use something like OpenAPI so that when you make those changes, it automatically updates your documentation.

So the things that change regularly find a way to actually automate that.

And the things that change less often, you should be able to then manage.

It’s also a good idea to put a last updated date on any particular diagram.

But if that can be automated as well so people don’t have to remember to update it, that’s also very useful.

But if you see something that’s, say, a year old, you know you probably can’t trust it.

If it’s only from last week, it’s probably fairly up to date.

So that’s already quite a lot of very useful advice.

In the legend of a diagram, would you also, because Judith would ask not just about abbreviations but also about what the box meant.

So would you also put a legend in there that says these are the boxes that we’re using or that’s the semantic of this box or that arrow?

Is that also something that you would advise?

Whatever you’re using to communicate, if it’s a solid arrow means a synchronous call and a daft arrow means an asynchronous call, you need to tell people what that means because that is a fairly typical thing to do.

But what if someone has swapped it over or they’ve used a green arrow to mean something, then you can get some, basically you don’t want people to misinterpret your diagram.

So give them all the tools to interpret it.

But talking about green arrows, that’s another thing to consider and that’s colour.

One of the things I talk about is not relying on colour to communicate because you get people who can’t see colours the same.

You get people with colour blindness and it’s not just don’t use red and green.

There’s, I think, seven different forms of colour blindness, which I quite often and anyone coming to AMA, you will see this in my talk.

It’s quite a fun anti-pattern to have a look at.

But we look at how we can, different ways that we can use, not use colour to communicate or use colour plus something else.

And I think problems with colour vision is actually quite common, right?

It’s not just a few percent.

It’s actually quite a percentage.

Worldwide, I think it’s 4.5 percent, which doesn’t sound very high, but it’s over 350 million people.

And it affects men more than women.

I think it’s one in 12 men and one in 200 women.

You can’t tell.

I’ve used these slides many times.

And so with the tech industry like it is, with it being more male dominated, you’re actually more likely to come across someone who is colour blind in the tech industry than you are in some other industries.

That’s something you really do need to consider, because if people misinterpret your diagram just because you use the wrong colours, then you’re going to get some very costly mistakes happening.

Yeah, good point.

Deirdre added another remark.

So he said, one solution that I evaluated for myself is the C4 model, where I try to get the diagrams generated from code or information that changes.

So C4 is obviously the model that Simon Brown advertises.

Yeah, the C4 model can be quite useful.

It’s all about structure.

So you’re still going to need behavioural diagrams.

You’re going to need things like flow charts and other sequence diagrams, things like that to show your behaviour, because structure and behaviour are both very different.

You can’t put them in the same diagram without risking confusing people, which is another thing I often talk about, mixing those together.

But, yeah, C4 can be really useful.

And a course that I created recently, which I now teach, is all about diagrams as code and how we can use them with AI.

And one of the things I teach in there is how to get started with Structuriser, which is the diagrams as code model version of C4, where you can actually just write it all as code.

And so you can keep that with your actual code as well.

So that’s particularly useful.

Yeah, and we had actually Simon on the show to talk about that, so I will add a link to the show notes.

That’s obviously also an English episode.

So can you give some more concrete examples of communication patterns?

Maybe not in the field of diagrams, because we talked a lot about that.

Other types of patterns that you can advise or that you find useful?

I’ll give you one example that applies to visual, but because it applies to other things as well.

There’s one called representational consistency, and that sounds complicated, but it isn’t.

It’s basically about when you have, say, multiple diagrams or other artefacts, things like documentation, your audience needs to be able to easily kind of see the link between these separate artefacts so that they can understand that whole picture.

So when you look at, say, a high level diagram, like a system landscape or a context diagram, if you’re thinking about the C4 model, when you look at the next level down, which is maybe a breakdown of that system, then you need to be able to see that link.

You need to realise that these two diagrams are connected and understand that connection.

So the C4 model has got useful ways of doing that.

So if you’re in the context level, it will have a dark blue system.

That’s the kind of thing we’re focusing on.

And then the next level down, that system where you break it down, that dark blue box becomes a dotted box around the edge.

And so you still might be looking at things outside of that dotted box, like the users.

But whichever one of those diagrams you look at first, you know the link between them.

And so when we’re thinking about documentation, say you’ve got things like a decision record, it might be an architecture decision record or another type of decision record.

You’re recording kind of why a decision was needed, what the options were, what the decision was.

And that’s really useful.

But it’s far more useful if you then link to where that decision record’s been applied in your documentation.

So when you’re documenting whatever is being designed or done, you then have a link from there to the decision record and preferably a link in the decision record to there.

And if they’re not actually hyperlinks, you just reference it.

You say this has been applied here or this is in decision record two, three, four.

And so you’re just referencing what you’ve done.

You can say, oh, the criteria we used to make this decision came from requirement 27 and 28 or from the constraint 14, things like that.

And it just means that when people look at that decision, they can go, oh, OK, that still applies.

That still applies.

That changed.

Does that mean that I can change this decision or it should be changed?

And you’re just giving people that information.

Also, it means that people can look at it and go, yes, I agree with that, because they’ve sort of given me the proof that I need to kind of trust this decision or this design or this this table of data.

And it just gives people that information to be able to understand and trust what what you’ve created.

But also kind of the ability to change things safely in the future, because every time we know that change happens all the time.

And to make those kind of safe changes, we need to understand why things were done in the past.

So we’re kind of linking everything together.

Because you brought up the subject of communication via e-mails, I was wondering whether you have some advice to be better at writing e-mails or is it just writing?

I mean, is there also advice on reading e-mails?

Yeah, there’s a bit of information on like writing on different types of technical writing and things in the second part of the book, which is all about written communication, verbal and nonverbal communication.

But there’s also loads on kind of this communicating with people who aren’t in the same room as you, because if you’re in the same room, you can just talk to someone.

But I mean, even a lot of people who work in the same room will just message someone who’s just over there or email them because they need to copy in someone who isn’t there or talk to someone else who isn’t there as well.

And so that’s kind of why I wrote the whole kind of distributed part of the book, because even if a lot of people are still co-located, they are still communicating with customers who are elsewhere or the odd team member who’s elsewhere.

And one useful thing you can do with e-mails is that you can make sure that you come to the point kind of straight away at the beginning.

So instead of kind of going, oh, because so-and-so is on holiday and because the school holidays are coming up and blah, blah, blah, blah, blah, we’ve had to change it, change the date and time of this meeting.

So can everyone let me know what their availability is and blah, blah, blah.

You just say that the new options for this meeting are blah, blah, blah.

Can you get back to me?

This has changed because.

And so people can actually get to that point very quickly and they don’t have to read the whole kind of rambling bit.

And if you look at like newspaper articles, they’re written in this way.

They give you the most important information first, then the next most important information, then the next most important information.

So you don’t actually have to read the whole newspaper article to get the gist of it and get the most important information.

So that’s one big tip.

Another one is putting in your subject header the important information.

So if it is just an F.Y.I., you can just put F.Y.I. or you can put reply required from Jackie and F.Y.I.

Dave or whoever.

And so people know instantly, oh, I need to look at this or, oh, I don’t need to stop what I’m doing to read this right at this moment.

So that’s another good technique.

Yeah.

Yeah, I think that’s very, very good advice.

And those are really great points.

I was about to ask.

You know, you might consider that even impolite.

So what do you think about that?

I mean, you know, explaining why this is the case and so on, at least in verbal communication, if you’re in the same room, that might be something that might be considered more polite and, you know, might be more useful.

So are we missing something there in emails in general, or is that, what do you think about that?

Yeah, it’s a lot harder in written communication to really communicate what you mean.

And I think that’s why emojis appeared first, just the text-based emojis, when that’s what we had on our mobile phones and then into the much more varied ones that we have now.

And so it could be quite a problem when you’re using forms of asynchronous communication.

Emojis can help, but I think actually, if you’re keeping things quite brief and professional and just generally polite, it can really help.

But one way that you can help, and this only helps you rather than other people, is to always assume good intentions from other people, because it’s very easy to misread what people have written to you.

And so if you always assume good intentions and reply politely and as you would if it hadn’t come across that way, then you’re not going to get a situation that kind of blows up.

Whereas, because if it was good intentioned, then you could then end up offending them by taking it the wrong way.

But if it was a bad intention, and it very rarely is, then you’re just kind of placating the situation and bringing it down anyway.

But yeah, assume good intentions from people, because it’s really difficult to communicate in text what you really mean.

Yeah, that’s a very good point, and it covers the question concerning reading emails in a way.

So trying to read emails in that way.

And I also like the point that you made, that even if it was bad intentions, it’s not going to get any better if you actually assume it was bad intentions.

So you’re better off assuming good intentions anyways.

What do you think?

Can everyone learn to be good at using these communication patterns?

I mean, obviously there are people who are more extroverts and introverts, and you know, there are these typical people, or it’s assumed that there are personalities who are better or worse at communication.

So can everyone learn to be good at communication with communication patterns?

I definitely think everyone can improve.

I wouldn’t say everyone can get to exactly the same level, because there are people who are really, really good at it.

And there are people who are starting from a point that is quite far away from what they might consider to be good.

But I think that although it’s a difficult skill to learn, I think it’s more difficult than a technical skill, really.

I think everyone can learn, and I think everyone can improve.

And with the, especially the visual part of the book, I start with what I call the foundations and say, right, here’s three things.

Do these three.

Do them consistently, and then you are at a really good point, and you can start looking at adding other things in.

And one of those is audience, thinking about your audience, which people say to me, oh, that’s the kind of thing you kind of taught at school.

But the problem is when people create diagrams, they actually forget about their audience.

They go, oh, I’ve been asked to create a C4 diagram for this, or I’ve been asked to create a flow diagram, and then they just make it, and they don’t think, well, actually, this is going to be looked at by the project manager and by the product owner.

Then they put a load of technical stuff on it, which they’re not going to understand.

And so thinking about the audience and getting those kind of foundations, the three things that I put in there, is what I say to people to kind of, you can focus on those, and if you get those consistent, then you can start adding these extra things in.

And it’s true for any skill, really.

If you go, right, okay, what’s important here?

Let’s start adding in these two or three things, and then start adding more in, and that’s how you get better at pretty much anything, really.

But let’s assume that you were asked to build a C4 diagram, and your audience are management people, non-technical people.

Does that even make any sense?

I think so, because C4 diagrams are generally, in very plain language, they don’t have, they might, once you get further down, they do have technologies on there.

But the ones that are further down aren’t particularly applicable for the non-technological people.

So when you’re at the highest level, people can look at that and go, okay, look, we’ve got our system, we’ve got a name on that system, we’ve got arrows, we’ve got the users, I can understand all of this.

And obviously, you should be putting a key or a legend in there, but C4 diagrams tend to be understandable, even without them, especially at the high level, because you’re not going into the, oh, this bit’s a queue, which is a cylinder on its side, and this bit’s a database, which is a cylinder standing up.

And that’s the kind of thing you need to put in a key, but at the highest level, you don’t have that.

So I think, generally, the C4 diagrams are for everyone.

Some people say to me, oh, yeah, they’re just for the business people, they’re just for the architects.

But actually, even the people who are working, kind of like the teams who are working on like one little bit, that’s like three levels down in that diagram, they should still understand the context, they should be looking at that top level diagram as well.

Not daily, but they should understand who the users are, and what systems are interacting with, even if their little bit doesn’t interact directly with those things, it’s going to have those things probably impact you in some way, there’s a bit of data that comes from that outside source that eventually gets to you.

And if you’re looking at that going, well, why, why, why is this changed, then you have some understanding of where that might have come from.

Okay.

So the talk that you’re going to give at the AgileMeets Architecture Conference is called Design Patterns for Software Diagramming.

How does that relate to your book and communication patterns overall?

So this talk is based on part one of the book, the visual part, and it’s a selection of patterns and anti-patterns for the diagrams and visuals.

It doesn’t cover them all, nowhere near.

I’ve realised I don’t actually cover them all in a one day workshop that I run on the same subject.

So I definitely can’t fit all into a 40 minute talk.

But it goes through a section of different ones from six chapters in that part.

And they’re all kind of about different things.

There’s one on notation and fundamentals chapter and things like that.

And so it gives you a nice selection so you can.

There are lots of useful takeaways from that talk, whether you end up reading all the rest of them or not.

So when I look at, I mean, obviously I’m also doing workshops and I’m drawing some ad hoc diagrams.

And I’m wondering whether you need to be good at drawing to actually use communication patterns or diagramming patterns for that matter.

I mean, at least if you’re standing in front of a whiteboard or a flip chart with your pen in the hand, do you have to write?

Or is there also some advice about that?

Yeah, I think if you’re if you’re actually drawing with your hand, then you don’t have to be an expert drawer.

But there are things you can improve so you can work on your writing being sort of a decent size and legible.

And one thing that I’ve picked up from looking at things like sketchnotes is that they say, don’t don’t write, draw the letters.

And so you’re actually kind of thinking about drawing the shape rather than just squiggling the letters as you go.

And it’s quite an interesting concept that it’s like, OK, right.

I’m thinking about drawing each letter rather than just writing them as a word.

And so I think practice is one thing if you do draw a lot with your hand.

But if you’re using computers, you don’t need to be good at drawing.

You can apply the patterns and avoid the anti patterns without any prior knowledge of drawing.

And applying those, of course, going to then improve your diagrams.

So if you’re using software like, say, Draw.io, that’s an open source app that you can use online or you can install it.

Or things like draw diagrams as code, plant UML, mermaid, structuriser, things like that.

That’s going to mean your diagrams are even kind of further removed from your hand drawing skills.

Of course, not all the patterns in the book are visual.

And so all of those definitely don’t rely on your drawing ability either.

But all of the patterns in the visual section can be applied to stuff that you create on the computer as well as things that you might draw by hand.

And actually, I mean, to sort of state the obvious, Lisa has written a book in German about sketchnotes in IT.

And there are also some exercises in there to get better at drawing.

It’s somewhat unfortunate that she couldn’t do this episode.

I guess there is a lot of sort of common things that you could have discussed with her.

So what is a good way to start with communication patterns?

What shall I focus on if I try to improve?

What are the first steps, in your opinion?

I think probably the best way is to identify kind of where you think you need improvement.

So if you’ve maybe had some feedback that something needs improving or you think, oh, OK, I think my my written communication could do with some improvement, then you can kind of just skip to whichever part of the book you want to look at.

So if you say, oh, it’s visual, then you can start with the foundations in chapter one.

And then one of those is the representational consistency and the audience, which I talked about earlier.

That’s another one.

You can choose to start with any of the other parts.

You don’t even need to read the parts in order if you want to.

But sometimes I do reference stuff that I’ve talked about previously, particularly in the same part.

But the whole book’s designed if people want to sit down and read the whole thing, they can.

Or you can just jump in any way you want or you can go, oh, I want to improve the stuff to do with my communicating knowledge.

I’m just going to skip to the knowledge part and I’m just going to read through all that bit.

And then I might look at the other bits another time.

So it’s it’s quite easy to read how you want it.

And of course, if you can go and reference it easily, you can think, oh, I’m not quite sure.

I can’t quite remember this.

And you can pop back in and and find what you need when you need it.

So it’s not something that you have to read from back to back, but rather you can sort of cherry pick the things that are most important to you and most interesting to you.

Yes.

Gernot, you said that I thought so.

So addressing me, I thought that you have already been infected in a positive way by Lisa with her sketch notes, which, by the way, are awesome.

Yeah, I agree.

But I mean, it’s something that that I definitely take away from from from this episode is that communication is just so much more than obviously drawing.

And also that it’s.

How shall I put it?

Sometimes a way to tell that that an idea is good is that it seems trivial if you if you once you’ve heard about it and there are so many things that you say that are sort of obvious once you heard them.

But you never thought at least me, I never thought about them.

But they are definitely great ways to improve.

I mean, that’s probably the the the point with genius ideas that once you tell them to people, it’s like, yeah, of course.

But, you know, to get to that point, I think that’s that’s great.

And there is so much stuff.

I have to admit that I haven’t read your book, but it’s really sounds like there is a ton of things to learn from very different perspectives.

Yeah.

What you say there about the kind of the simplicity of it.

Some people say to me, oh, it’s really obvious that you should put a key or a legend in a diagram.

And I say, well, look at all the diagrams around you and tell me what percentage of them actually have a key or legend in them, even in, say, the same web page, even if it’s not with the actual diagram.

And it’s incredibly low.

So people say this is so basic.

Like, yeah, but people don’t do it.

So I just have to remind people, give them the best practices.

That’s a very, very good point, because it illustrates my point exactly.

And also, I have to admit that one of the things that I tend to ask if some diagram is presented to me in some review or in some session is, OK, so what’s the semantics of the box and the arrows?

Because usually there are box and arrows.

And oftentimes, it turns out that it’s actually sort of undefined.

There is no clear definition.

And then the whole discussion becomes messy.

So putting in a legend, so that would become obvious once you put a legend in there.

And I wouldn’t ask that question if there was a legend.

So what you said is very true.

I would say that almost all of the diagrams that I see are boxes and arrows with, let’s say, loose semantics.

And that’s a problem.

Yeah, this one’s a thing, and this one’s a thingy.

Exactly.

So does that represent the real system, or is it something that you’re aiming for?

And then you figure out that it’s actually both, but in different places, it’s either one or the other, and so on and so on.

And then it becomes pretty messy pretty quickly.

So therefore, it’s a great idea to put in a legend there.

So Jude Root asked the question, what is your take on storytelling as a communication tool?

And I assume – I’m not sure whether this is specific to domain storytelling, what Henning came up with and Stefan from WPN.

I think this is probably storytelling overall.

Okay.

And that is a topic that I do study. doing this, and then we’re doing this, and then we’re doing this.

And that’s creating those connections as well.

And storytelling is really interesting because it’s how we evolved.

If you think about it, we didn’t start writing until a long time after we were communicating with each other.

We were even communicating by stories and talking to each other before we started kind of drawing as well.

And so our kind of verbal storytelling was really important because it’s how people passed information on to others.

And then that developed into the visuals as well as the verbal storytelling.

And so story is really important to humans because it’s how we evolved.

And that’s why when you get kind of disjointed information, it can be a bit of a problem because your brain goes, I need to understand the link between that and I need to understand why that happened before that and what order things have happened in.

So this is a really good question.

I think storytelling is really important and not just when you’re, say, doing a presentation to people.

Then it’s really important because you’re kind of controlling the whole narrative and the timing and the order that you say things.

And we don’t tend to think about that when we’re creating diagrams and documentation and other forms of knowledge and communication.

And so putting things into kind of a narrative really helps.

And with diagrams, you do this as well.

So let’s say the C4 diagrams, they’re on different levels.

If you were talking to somebody about something, you don’t just jump to the bottom level of detail because people need to kind of understand the context of that.

And so you start at the top, then you go down a level, then you go down a level.

And depending on how much understanding people have is how long you have to spend at each level.

So if people have lots of understanding, it’s just, here’s a quick reminder, here’s a quick reminder, here’s what we really need to talk about.

And if people don’t have any understanding at all, you’re going to spend a lot more time explaining things and going through stuff.

And so it all really comes back to kind of audience as well.

And all these different patterns, anti-patterns, they’re all connected together in that way.

And so that’s another thing with the connections and the story through them as well.

So is storytelling means connecting things together?

Is that what you’re saying?

Kind of.

It’s thinking about the order of things.

If you think about writing a fictional story, you have very basically a beginning, a middle and end, or you have a kind of an exposition at the beginning, you’re kind of introducing the characters, and then you kind of introduce a bit of tension, the kind of like, oh, what’s going on here?

What are the constraints?

What are the needs and things like that?

We’ve got the scene from the beginning.

Now we kind of get the tension kind of building up.

Then it’s kind of like, OK, this is what we’re really going to do.

This is what’s happening.

And then you kind of get that ending of, and then it’s done.

And although that’s kind of the fiction thing, you can kind of think about that same thing when you’re communicating to people in different ways as well.

So connecting, as you said, from top to bottom and therefore having a story that goes through several diagrams, these kinds of things.

OK, makes a lot of sense.

I’m wondering, so I’m just wondering, I think we covered most of the book, right?

So we sort of spoke about remote and graphical visual things.

You made another point about communicating knowledge.

Didn’t you?

Or is that like the…

Yeah, that’s another one of the parts.

So it’s…

There’s things like documentation included in there, but it’s all about all the different ways that you can communicate your knowledge.

So it’s how am I going to present this information?

How am I going to document this?

And, yeah, so there’s the four different parts.

You’ve got the visual part, then you’ve got what I call multimodal communication, which is a kind of umbrella for the written, verbal and nonverbal.

And then we’ve got knowledge, which includes all the documentation and the ways that you can share knowledge between each other.

And then the last bit is the…

I think it’s that order.

Yeah, knowledge, I think it’s part three.

And then the part four is the remote communication as well.

In the knowledge section, I talk about things like decision records, like I mentioned earlier.

So there’s a whole section on…

It gives you the basics of decision records, but also how you can use them more effectively.

Because I know other people have talked about decision records, but it gives you some tips for how you can use them more effectively as well.

And so there’s lots of useful bits like that in there.

Yeah, so there was one thing that just crossed my mind, because it seems to be something that I see a lot in my consulting engagements.

So there is a group of people and they develop some piece of software.

And then people notice that, in fact, when one of them goes on vacation, then whatever that person does, it’s not something that anyone else can do.

And of course, they are scared, because once one of these people quits or is on vacation, you do have a problem.

And then usually what those customers say as well, we need to write a lot of documentation, because once we have the documentation in place, we have the knowledge in a different format, and we can have someone else look at it, and that person should be able to do whatever that person who is on vacation was originally meant to do.

And I tend to say, well, you know, that really doesn’t work, because documentation becomes outdated, it has the wrong details and these kinds of things.

And my advice would be to do something like pair programming, because obviously if everything that is done in the code is by two people, then you can, well, if one of them goes on vacation, it should be easy for the other one to do the same work.

So in a way, this is sort of replacing written communication with direct communication.

And I’m wondering what your take is on this, because it sort of seems like, how shall I put it, it doesn’t feel like a very elaborate way of dealing with that problem.

It basically just says, okay, get two people, put them in front of the computer and you should be fine.

So I was wondering whether you have any more elaborate ideas or whether you would disagree and written documentation can actually go up to that level that those people could be replaced.

So what’s your take on that?

Yeah, that’s a really interesting question.

And I think it’s going to be one of those ones that really depends on the situation.

So when I was talking earlier about updating diagrams, I said about the fact that the more high level stuff doesn’t tend to go out of date.

And so I think it’s really useful to have documentation that does have that high level stuff that doesn’t go out of date.

And if you can think about documentation and design it in a way where instead of it all just being, say, in one big page, that you do have the higher level stuff, and then it goes down a level and goes down a level.

I think that makes it a lot easier to update and keep it maintained, because you can say, oh, this stuff, it doesn’t change very much.

This, it does change more often.

And I think that can help.

I do really like the idea of pair programming and bigger groups as well.

I think that is a really useful way of sharing that information.

Of course, it gives you a certain level of protection.

If you’re only doing pairs, then you’ve got two people, which you could lose both of them in some way.

They could both want to be on holiday at the same time.

And it’s not particularly fair to say, oh, no, you can’t go on holiday because they’re on holiday.

So, but the rest of the team is here.

So that’s one thing to think about.

But I think there’s, I’ve recently been reading a book by Donald Norman, which is The Design of Everyday Things.

And I’d recommend it, it’s a really good read.

But he talks about the fact that there’s knowledge in the world and there’s also knowledge in the mind.

And so the knowledge in the world would be your documentation and the knowledge in the mind would be the stuff that’s not in the documentation.

But there’s also stuff that is also in the documentation because you’re not, you don’t reference the documentation all the time to do what you need to do, do you?

And so it’s getting that kind of balance between what’s in the world and what’s in the mind, because people will need to get that stuff that’s in the world into their mind to be able to then use it efficiently.

And yeah, finding that really important thing that only one person or two people know that isn’t then documented can be a big problem.

But I think, as you said about pair programming, doing more collaborative work, where you kind of sit down as a group and talk things through.

So doing the different things like the event storming and as you mentioned, domain storytelling, doing these collaborative activities and actually talking to other people and sharing information means that you will get less of that problem.

But I think, yes, having really important information, important workflows, when you get a recurring bug or a recurring problem, get those things documented.

But you’re going to get, as you say, with having everything in documentation, you’re going to get less and less back from having stuff in as you get more and more in there, because you’ve got the most important stuff in there and then you get the maintenance costs of it.

So you’ve got to get that balance.

You can’t just document everything.

So I took some sort of ideas from what you just said.

So I think one thing that you didn’t really say explicitly, but I sort of get the idea is that you definitely want to have some kind of overview as a diagram, because that’s also what C4 says and it doesn’t make…

I mean, that’s something that is not solvable with pair programming.

And it might also come back to, well, creating a diagram takes some effort, but once you reuse them, then it might be more useful.

And another thing that you said is those collaborative approaches, that they are useful.

And that’s also a good point, I guess.

If you do these diagrams together, not just one person sitting there, but rather many people are writing the documentation together, then that’s also an exercise in itself that provides better information about the system and might be useful.

So maybe expanding the idea of pair programming to sort of pair diagramming or whatever you want to call it.

So I think that’s…

There’s a technique called bytesize architecture sessions, byte with a Y, the bytesize architecture sessions.

And that is a very useful collaborative technique when you’re thinking, oh, we actually need to document our system a bit and work out what we’ve got here because we haven’t got the documentation.

So that’s a good way to do it if people are interested in those sort of techniques.

OK, so how does it work?

So it’s all about kind of getting everyone together and it starts off with like some individual time.

So everybody gets time to just, I think it’s very short, sort of three to five minutes, where, say, you’re focusing on a particular part of the system and everybody by themselves, say, creates a diagram, hand-drawn or on the computer, whichever they want to do.

And then you come together and produce that kind of same thing as a group.

And the reason you kind of have that alone time is so that you don’t get those people who are kind of the people who talk all the time kind of taking over because there’s probably someone who knows something and it may not get in because they’re quieter or don’t want to speak up.

And so you do that.

And then you kind of create something together and then you come back for another session.

You either work on that more or you work on the next bit.

And so you keep going until you’re sort of happy with where you are.

And always using the time by yourself and then in the group and in sort of consolidating what everyone has created.

Yes, that’s actually very, very smart and a very good point.

So if you could only give one hint to the audience to start getting better with communication, what would your hint be?

I think, like I mentioned before, it’s going to be considering your audience and what information they need, because a lot of the other things I talk about come back again to thinking about your audience.

So the artefacts you create, be they diagrams, tables, step-by-step guides, they need to answer your audience’s questions in a way that they can easily understand.

Else, why are you actually bothering creating them?

Your audience, they shouldn’t need to use much of their kind of precious brainpower.

We all have only a certain amount of brainpower.

If you have to use a lot of it, they’re either going to either give up or there might be some kind of miscommunication.

And so if you make things easy to understand, easy to find the information they need, and help them to build an accurate mental model of the system or whatever you want them to understand, that sounds deceptively simple, but it isn’t.

And that’s why I wrote the whole book about it, because there is so much to consider in there.

But audience is going to be one of the big things that you should be thinking about.

Okay, great.

So there is one question in the chat by Deirdre.

And he says, or asks, do you have recommendations on how to deal with too much documentation when you end up with a huge confluence that is kind of semi-structured?

I think a lot of people end up in that problem where people are just all adding their own documentation.

So you can, even if you don’t have the support further up, you can structure it a bit yourself, not by moving things, but by creating, say, a page that then links to things and structures it.

And if you end up with, say, people coming to your, call it a front door, you can then link, obviously, outside of confluence or whatever you’re using as well.

And you can create this kind of main homepage or front door of things.

And once people start realising that that’s useful, then you might actually get things restructured.

Another thing to think about is if stuff is out of date, mark it as out of date.

Make it really obvious what is out of date.

Make it obvious what isn’t maintained, because not everything should be maintained.

So if we are thinking about a huge amount of pages in here, just make it obvious what people should be reading, because if people get a long way into it and then suddenly realise, oh, wait a minute, this doesn’t sound right, this is talking about Windows XP, then they’ve wasted their time, haven’t they?

Or they might not even realise.

So make sure that you are marking whether things are in date or not.

Yeah.

So what I find interesting about this is that you pretty much describe sort of a per se for the documentation, like the original GovPattern per se, where you would just put in a simple interface to make a complex system accessible.

And the other thing is like deprecation, where you basically say, OK, this is deprecated.

So it’s interesting how you can sort of use the same patterns for code and for documentation, it seems to me.

Yeah.

OK, thanks a lot for being here.

Thanks a lot for spending the time with us.

I hope we will definitely meet at Erzschirmitz Architecture, I guess.

And I hope we will also meet quite a few people from the audience.

So have a great weekend and see you soon at Erzschirmitz Architecture or other conferences.

That’s brilliant.

Thank you very much.

And if anyone wants to find me after this, best place is my website, which is JackieReed.com.

Really easy to find.

Yeah.

Thanks very much.

We will also put the link in the show notes to that page and also obviously to the page for your book.

OK.

Talk to you soon.