Lesson 224 - Creating an Architecture Narrative Transcript, AI Summary & Key Points

00:01 Hello and welcome to Software Architecture Monday. My name is Mark Richards and in this lesson number 224, we'll look at how to create what's called an architecture narrative. I was recently working with an architect who was struggling to convey their architecture solution to the product owner and other business stakeholders and asked me for some advice.

00:23 Well, it dawned on me that I never did a lesson on this topic about how to create an architecture narrative. What's included when you say you have an architecture solution? And that's what I want to do in this lesson. Because all too often, here's what happens. The architect will say, "I finished creating the architecture for the new system." And the business stakeholders say, "Great.

00:52 Let's see your solution. Okay, here it is. Um, the business stakeholders look at this complex architecture diagram and say, "What is this? Can't you describe your solution in a way we can understand it?" And of course, the architect is saying, "I don't understand what you mean. This is the architecture. This is what we use. We diagram architectures, but we don't understand what your solution is here."

01:20 And at this point there's kind of a lot of confusion. Everything comes crumbling down and the architect and business stakeholders part ways usually not meeting up again. This is a very common problem. What I want to do in this session is or this session this lesson is really about creating an architecture narrative. what's included in an architectural solution and how to properly uh uh dis uh present and explain your architecture solution.

01:53 Turns out we can borrow a lot of things from literature and movies. A great story and a great movie and a great book all leverage what's called a narrative arc. Let me explain this narrative arc. So along the bottom you'll notice that we have the story progression. This is the timeline of the story. However, the other axis is tension. And as we start to look at a story, we start with the introduction and exposition.

02:25 It's the beginning of the story. There's not a lot of tension, unless you're watching the beginnings of of a James Bond movie. [laughter] But this is where you get an idea of the setting, uh, the people, the characters. And then we move on. As tension in increases during the story, we start to get some complication finally reaches up to the climax of the story which then everything resolves and the story ends.

02:54 Well, it turns out that great books and great movies and great storytelling utilize this narrative arc. And as a matter of fact, we can do the same thing with architecture. Now, diagrams are a key way of us as architects to be able to describe an architectural solution, but they're only one part of the storytelling about our architecture. We can actually leverage this narrative arc.

03:31 First though, let's back up and say, wait a minute, what's included in an architectural solution that I'm trying to present or convey to other stakeholders? Well, certainly in obviously there's various architecture diagrams and views and this sort of thing, but there's a lot of other components. There's also your architectural decisions typically written in ADR format which talk about the context and the justification for those decisions.

04:02 We also have alternatives that we describe and these are the other things that we may have considered. Of course, as you know me, there's always trade-offs that we indicate in our architectural solution, things that we had to forego to get other kinds of things. Also, there's constraints that we describe certain technical and business constraints, whether they be frameworks or services or third-party tools or libraries or systems that we have to incorporate or maybe it's business constraints in terms of time and cost.

04:37 Uh there's also the business problem itself. There's driving characteristics, those capabilities that the architecture needs to support. And finally, any sort of unique challenges that we faced. Now, I have seen architects utilize all of these components in their architectural solution, but it's not telling a compelling story. So one of the first steps in creating an architecture narrative is to create a proper story, a flow of guiding the viewer of your architecture through the journey that you actually went through.

05:20 One effective way of doing this is overlaying the narrative arc where we have introduction and exposition where the business problem is all the way to all the complication uh all of those illities like scalability that is going to be hard to achieve or maybe it's technical or business constraints unique challenges and finally our resolution. So let me describe how we can actually leverage the narrative arc for architecture for telling and describing our architecture and its corresponding story making it compelling to

05:58 actually read. There's something I want to introduce that lays on top of the narrative arc called the threeact structure. Now a three-act structure is another way of storytelling. It's how movies and plays and books and music are also structured. So laying on top of this narrative arc is act one. That's the setup. It overlays that introduction and exposition that we just saw from the architecture or from the narrative arc.

06:33 Then during the complication piece, we have act two, which is confrontation. And finally, the climax and resolution of the story forms act three, resolution. So let's take a look at how we can build an architecture narrative, how we can tell our architecture story. And let's start at the beginning, which is the setup. So in this setup, this is the introduction and exposition.

07:02 Essentially, what we're trying to do when we describe our solution is saying, "What is the business problem we're trying to solve?" All too often, viewers of our architectural solution don't necessarily have the business context. And in here, and what's included in this part of our architectural description is what is the context of the problem that we're trying to solve?

07:28 Also, why is the business doing this? We may be going through a major migration from a legacy system to a distributed architecture. It's nice to know why the business is doing this and the corresponding business drivers that gives us more context in the story. And finally, who are the stakeholders and major players involved in our architecture solution?

07:57 Now, this is where we really describe that business problem. And I want to emphasize this is not reiterating all of the business requirements. These are concise paragraphs that convey the vision, the rationale, why the business is doing this, and simply who's involved. Now that we've got the setting, now we move on to confrontation. As time progresses, tension increases.

08:23 And in architecture it certainly does where we get complication. And in here what we're really describing are those conditions and constraints that we faced as architects. When we show an architecture solution as architects, many times we don't convey all the pain that we had to go through in forming our solution. This is the place to provide that context.

08:52 In other words, here we start describing what are the business constraints and also technical constraints that we faced in forming this solution. It gives viewers, stakeholders some sort of context in terms of why we chose certain things the way we did. Also, what architecture characteristics do we have to support and tie those back to the business requirements?

09:20 That's all part of the complication uh that forms our decisions and our trade-off analysis. Here we describe some of the unique challenges that we're faced with this business problem and it could tie into some of those constraints. But sometimes we have some unique challenges that we're facing. And finally, what are the alternatives and corresponding tradeoffs that we encountered?

09:45 All five of these components all are wrapped up into act two. This is our journey. This is what we faced. Those demons that we had to overcome, those obstacles that we had to overcome. Finally, we move on to act three, the resolution. Here, this is where most architects start [laughter] in describing an architecture. Here it's at the end. We've handheld the stakeholders through a journey, a narrative of our architecture.

10:21 And here now we describe the proposed solution. What is that proposed architecture? Um have we effectively used illustrations and diagrams to be able to convey that architecture in the best way possible of that shared understanding of our solution? Also, here's where we put those ADRs, those architecture decision records. Those come after the conflict and also that confrontation, that complication because that's what forms our architectural decisions.

10:54 And finally, here is where we put the risks associated with our proposed solution, including the ADRs and diagrams. This is a very effective way of being able to describe an architecture as storytelling, something that makes it compelling for the reader to view. Now, in future lessons, I will take an I'll I'll dedicate a lesson to each of these acts in the next three lessons, although I may have to interrupt it a bit to introduce some new books that Neil and I are now finally releasing this year and the beginning of

11:36 next. But uh for the purposes of the material, this will be a road map for the next three lessons where I'll dive deeper into each of these acts and explain uh and show examples of an architecture narrative. So this has been lesson 224, kind of an overview of creating an architecture narrative. Stay tuned next month and the next three lessons when we dive into each of those acts and what's involved in creating that story of our architecture. Thank you so much for listening.