Keeping track of architectural-ish decisions in a sustainable way with Juan Saavedra

This video features Juan Saavedra at DjangoCon US 2022 in San Diego, California, USA.

Keeping track of architectural-ish decisions in a sustainable way with Juan Saavedra
0:43:57
Published November 3, 2022
458 views

More often than not, keeping track of decisions made in the context of software development is… challenging. Many developers have faced picking up seemingly well-documented projects where the rationale for a decision is, at best, available... somewhere. If you keep thinking about it, you might find something is odd. Is it actually that hard? Are we using the right tools?

We will present Architectural Decision Records, a (not so) novel approach that tries to capture that rationale in a lightweight and unobtrusive way. We will introduce the concept, go through some fundamentals and present a sample case from our experience and how it has reshaped our decision-making.

This talk was presented at: https://2022.djangocon.us/talks/keeping-track-of-architectural-ish-in-a/

LINKS:
Follow Juan Saavedra 👇

Follow DjangCon US 👇
https://twitter.com/djangocon

Follow DEFNA 👇
https://twitter.com/defnado
https://www.defna.org/

Summary

Juan Saavedra argues that teams regularly lose the context, alternatives, assumptions, and trade-offs behind difficult-to-change technical decisions, making onboarding, reflection, and later change harder. He recommends Architectural Decision Records (ADRs): short, developer-oriented records covering context, options, consequences, and status, including when a decision is superseded. Using a notification-system example, he shows how decision drivers and concise pros and cons can guide a practical, low-effort process that teams adopt as part of their normal work.

Key takeaways

  • Architectural decisions are difficult-to-change functional or non-functional choices, regardless of whether they fit a strict definition of “architecture.”
  • ADRs should record the context, alternatives considered, consequences, and current status, including superseded decisions.
  • Decision drivers such as risk, latency, operational cost, and schedule help teams compare options without relying on vague pros and cons.
  • ADRs are intended for technical readers and should remain short and practical rather than becoming exhaustive documentation.
  • Keeping ADRs accessible near the code or in a team’s usual knowledge base creates a timeline that supports onboarding and future reassessment.
  • Teams can adopt ADRs incrementally by recognising decision-worthy discussions and recording them as they arise.

Summarised automatically from the transcript.

Chapters

  1. 0:00 Introduction and Talk Overview Juan Saavedra introduces himself and previews the problem of architectural decision documentation, ADRs, and a live example.
  2. 2:39 The Lost Context of Technical Decisions A new-team-member scenario illustrates how rationale, alternatives, and assumptions disappear from a project’s documentation.
  3. 11:45 Architectural Decision Records The talk defines architectural decisions and introduces ADRs as short, practical records for choices that are difficult to change.
  4. 18:43 ADR Structure and Content The speaker explains the four essential ADR elements—context, options, consequences, and status—along with templates and where records should live.
  5. 24:08 The ADR Cooking Process The live walkthrough begins, covering lightweight decision-making, shared architectural characteristics, and the setup for a delivery-system example.
  6. 26:28 Framing the Delivery Alert Decision The example establishes the last-mile delivery system, its notification problem, project constraints, participants, and decision drivers.
  7. 31:54 Evaluating the Options Firebase and WebSockets are compared through concise pros and cons tied to the decision drivers.
  8. 34:59 Recording the Decision The example selects Firebase, documents its trade-offs, and shows how the record preserves assumptions for future changes.
  9. 37:16 Benefits and Adoption of ADRs The speaker summarizes how ADRs clarify assumptions, build consensus, support onboarding, and reveal when old decisions should be revisited.
  10. 40:31 Questions The audience asks about incorporating ADRs into team habits and applying them to mature architectures.

Transcript

6,537 words · auto-generated Show

Automatically transcribed, so expect mistakes in names and technical terms.

0:20

Speaker 1: So, hi everyone. Um Uh I'm Juan. I 'll be talking about this today. If you didn't read like the description of the talk, this is going to be about documentation. So uh heads up, I'll try to keep you uh It's a good thing it's before lunch, so I'll try to keep you up and running the whole uh talk. So briefly about me, I don't want to take too much time. I'm from Uruguay, Latin America. Um I have two kids. uh boy and a girl. Um I'm a CTO co-founder of Arctobot as Jorge was saying, uh self-work consultancy agency. Um we do a lot of US based um Development work with a lot of Django.

1:05

Speaker 1: It's my second time talking here, so I'm so glad to be to be back and I'm a huge soccer fan So let's get that out of the way. What we're talking about today. So um we're talking about the architectural decision. So is is there a problem? The first part is try to like frame what we are facing, what sort of the problem that At least I saw, and it seems to be a popular opinion out there that there is a problem. What are architectural decisions? So what is the thing that um sort of Escaping that we are not recording. This instrument that I want to introduce, if you don't know it,

1:53

Speaker 1: that's called Architectural Decision Record. Then we'll do live cooking of an ADR and as with most cooking shows I'll have the dish ready just in case and some takeaways. So one of the first things I want to note is that I learned about these things from this book. I have no affiliation with O'Reilly or whatever, but I strongly recommend it. Because it it really helps to push out the boundaries of the unknown, you know, the unknown known, the unknown, unknowns, and the unknown, unknowns. So I think it's a great tool to do that. And I le Turn this about here And just with just want to point it out that that I strongly recommend that. So

2:39

Speaker 1: is there a problem? Let's speak about what brings me here. So um you tell me let's do like this sort of role-playing. You are a Django developer in a project or web developer whatever. Um you've been doing two years, maybe from the project start, maybe not, you're on boarded, but You sort of gotta have a good grasp of what the project is about. And you've been trying to get somebody else to onboard your existing team, like and one day that happens and you got a new coworker. And so that coworker is Mindy from Animaniacs, the Y Girl. That 's everything

3:24

Speaker 1: Y. She's now a semi-senior Django dev because she's probably mid-20s, something like that. And you gave her the usual welcome back. So it's like, hey Welcome to the project, so glad we have you. Here's the code, the access, sort of like small walkthrough, maybe some high-level docs. Like, hey, start reading this. And we'll meet like two days a week and we'll go do an overview to see if like how you're catching up. She's like, great. And so you run this intermeeting. And so you start uh

4:09

Speaker 1: she's like, hey, which git branching strategy are you using? And you're like, yeah, we're using like, I know the GitHub branching strategy. Why? And it's like you know, it's like no sort of convenient because It's sort of what we've used and okay. Great. And you're like, hey, what DB backend you're using? And like, yeah, you saw that I saw in the settings, you know, passwords. All right. Why? Why are you using posters? So you're starting I don't know. And and so you start getting to these questions

4:55

Speaker 1: like it's not that those decisions are wrong, but You start thinking like why? Are you doing like templates or like rendering? Um no no we have a REST API and a separate web app or we're doing Graphic Google Let's say you have a Django REST framework. Great tool. Why? Why do you use REST? Okay. And so these kinds of questions Mindy could not get the answers from what you have out there. And she's relying on you, the team, to get to that information. And a lot of the times that information

5:41

Speaker 1: is either not there because nobody asked the why question or it's lost. So eventually somebody say, yeah, we're using REST, REST framework, but that's gone. So what's happening? Proposal. So we are regularly losing relevant information of that sort of decisions we are making. So this Like, hey, how are we going to solve this problem? How are we going to do that sort of like I I hope like everybody has been in one of those? There is this thing that is getting lost Particularly what 's getting lost is the context. So what was the context that you took?

6:27

Speaker 1: This alternative and also the alternatives that were considered. So you are uh effectively losing a bit of this information. I'm going to risk this and say a show of hands for people that has been in some sort of similar scenario or disinformation. Great. I have something to sa to uh to tell you. Uh so now you might might say, hey It would be great if we have this, but perhaps it's not a problem, you know? Not necessarily everything that's not good is a problem. So I have like this take that it's not only me, that this is a problem.

7:12

Speaker 1: So first, why is this a problem? Because we cannot Reflect, we cannot reliably at least reflect on our decisions. We cannot say, hey, did we consider this? Like this option when we decided on like was GraphQL even on the table? Was that a thing? Um or is this like this is thing that's happening? Did we agree on this? Did we envision that this was something that could happen if we make this choice? A lot of the time you don't have some like cold record of that. It's hard to onboard new people. If you new people come, it's like Why are have you made all these decisions? Have you considered X the past? And it's like yeah yeah so

7:58

Speaker 1: it's hard for new people to come on board and understand the rationale behind those decisions And so a side effect of that is that knowledge hoarding sort of naturally uh appears because it's not that they have this effective way of like Taking that knowledge and putting into something that other people can read. And also evolving is challenging. So you when you have when something changes You might need to adapt. You might not, but understanding when you need to adapt implies that that change impacts Your assumption. So you have this change is

8:43

Speaker 1: like, hey, does this change impact in any way some of the assumptions we have made for decisions in the past? There is no Clear way to make that call if you don't have this sort of like way to persist that knowledge, that context, that options that were considered. So what's causing this? Well, perhaps our regular tools are not specifically designed to this They are not able to capture the changes. They're more like current state of affairs, but we don't have like the deltas. And also you don't have the why. Why did you make that delta in that direction?

9:29

Speaker 1: And when I say specifically designed, just to be clear, it's like there is no field usually in a Rhythm for like, yeah, yeah, we changed this because what? This is just a freeform thing that's not specifically designed for that. So I went on and like looked for current tools. So perhaps ah by the way. Um Perhaps these tools are not there. So what do regular tools look like? So I went to confluence like decision-making template and this popped out. And it's like it's not bad. Like you have to go in and feel stuff, but you're like the outcome, what what what should I put there? What what should go there? And to like what's a pro and con for an option?

10:14

Speaker 1: Why something on pro and con is like everybody agrees on what a pro and con is, but does everybody agree? So there is a a catch there The cost. So there is like pieces of information that we need to fill in that is like maybe unclear, or you're not sure how to perform that consistently But it's a good start. So in the lightweight part of the spectrum we have this. On the harder part of the spectrum we have people like People at NASA that have these missions that span sometimes decades, like Juno, James Webb Space Telescope, you are making a decision now that will impact how things work ten years from now. And

10:59

Speaker 1: they well they have like master thesis on decision making and what should we capture and the sociological factors and the whole thing. But it's super thorough and costly. They need that, but on fast-pacing agile environments Are those real tools to tackle what we need? Are those effective? Maybe not. Uh so one of the people have been working in this and they have found out that the assets that were or are out there to capture this sort of information are not effective in some industrial scenarios. For instance, web development. And so because

11:45

Speaker 1: you have like this sort of agile, fast-paced development A lot of times. So the tools that are there are not effective that they get in the way more than help you out. Right? So I felt that Likely other people felt that the same and uh backed that with a bit of evidence. So the tool might be wrong. So I will speak about decision records that is this Not new but new thing that I want to present and they try to capture this thing. What is this thing? Well this thing is an architectural decision This is the thing, uh the the Italian hand is because the

12:30

Speaker 1: only emoji and I'm familiar with that so um That is the thing that we need to capture. And what what does that look like? So Just to be like cover the formal, um an architectural decision is a software design choice that addresses a functional or non-functional requirement that is architecturally significant Next question is what is something that's architecturally significant? And so there's that. An architecturally significant requirement is a requirement that has a measurable effect. on a software systems architecture and quality. I'll just leave that there so it's cover the formals.

13:15

Speaker 1: This acronym won't come back, this definition won't come back, and we'll go on to more like rule of thumb stuff. to cover but I do want to point out there. So the short form of this like what is an architectural definition? What we are trying to grasp is something that is hard to change. So we are changing something functional, non-functional that is hard to change. Sort of like the two-way doors, one-way door analogy that like Amazon had and stuff like that. One of the good things about like framing architectural decisions this way is like it really uh distresses the architecture part. from the the concept. So we are not pushing the taxonomy on stuff. It's like, oh, is this architecture? Is this not architecture? Don't bother.

14:01

Speaker 1: Just say it's something hard to change. So that's sort of the short form. I have an heuristic to sort of understand when we are facing an architectural decision. It's like, is this an architectural decision? The first one is um We need to meet to discuss this and like that's like Q you're on to an architectural decision there. What framework should I use? Is this view? Is this React? You're facing an architectural decision. Um And finally, hey, we could use this brand new thing that just came out that's right for our problems like maybe we could, maybe we don't. But that sort of like

14:46

Speaker 1: um questions that I hope a lot of people come through eventually do match as an architectural decision. Others like Should we build this? Should we use something existing? Some infrastructure calls, you name it, that's sort of like what we are trying to capture. Architectural decision. So what is this tool I'm presenting? So the architectural decision record uh is A short text description. We'll see like it's like one page, two page long, no longer than that. It was first proposed by Michael Last name I won't pronounce out of respect , but there's the

15:32

Speaker 1: actual link when he proposed that and has seen adoption and From that time now on. So like ThoughtWorks in their tech radar now is like marked it as adopt. And so this is this like text message and so the most important part is that it's very practical to fill. So, and that's the spirit and the essence of what an ADR, I'm going to use the acronym from now on, that's an architectural decision record, on what an ADR is like. So it's something that's very practical to fill, that captures This and we'll cover what what needs to capture. And it's written sort of like this message for a future developer.

16:18

Speaker 1: So like these meshes in a bottle, stuff like that, like hey, we're stuck on the island and we're trying to build a boat and boom Message in the battle, that's sort of the spirit that we are trying to convey here in what we will be writing. Uh so Lee here uh spoke yesterday about logging and so this sort of has the same thing. He's saying uh when you log you have like captain and pilots might relate to this. Same goes here. Captain and pilot might relate to this, but hopefully software developers will do as well. So it's this journal. You'll be rec recording stuff and making notes on like Certain decisions that you will make in. Um there is this, I put this link, so there is this blog post that's very brief but very good from 18F.

17:09

Speaker 1: Something from the federal government that's the software, but it's very good. I'll I'll strongly suggest if you're interested in this to follow up and read that. But that's sort of the spirit of this One important part of this is that ADRs are for technical people. So they're intended for developers, like technology stuff, people that is able to read like technology written things. Why? Because it should be practical to feel. We don't want to explain everything. If you are like Python is an interpreted language that will describe very good semantics. Django is a brave framework. The web is, and so if you start doing that sort of explanation because you want everybody to understand your ADR

17:55

Speaker 1: It's just not practical to fill. So the idea is that other roles at your project, business people, we good. No good. Yeah, good. Um I I uh the hand thing is g going to keep happening. So other um docs might be more suitable for those kinds of positions and that's fine. We might use it eventually to justify some decisions like hey we did take this decision because X and I can explain it to you but it's not meant for you to read straightforward without some context and some background formation

18:43

Speaker 1: So what's in an ADR? So there's four things. First, context Why this change need to happen? Why now? Why not before? It's like somebody something changed that you need to make this call now. What needed to be considered? Like what is part of the context that we are placing into our process right now that needs to be considered in this discussion? The options. What are the alternatives that we are currently considering? This is super important, for instance, if in the future a new alternative appears that was not considered back then. Even if somebody new comes along and they can say, hey, have you considered X? Yes, we have, and we said no in this decision.

19:29

Speaker 1: Uh what were the pros and cons of each? Like maybe a can back then is no longer a can now and we can re-evaluate The consequences. So what will happen as a result of the change? Both in a good way and a bad way? Decisions are always about trade-offs. So you're making the saying, hey, I want this. And we are willing to take this luggage with us and that's fine. And so in the future say, hey What's this thing here? Yeah, yeah, yeah. We decided back then that we prefer this so we can get this. And the status. This is one of the most important parts for me because well this has like the very intuitive like proposed, accepted, implemented

20:16

Speaker 1: But it also has the superseded part. So this is the status that you'll say, hey, this EDR has been superseded by this decision. So you start to get a timeline once you do it consistently over time of like Hey, we decided X and this like overcomes decision in the past. And so you don't drop that. You say, hey, back in the days we decided this. That was superseded by this new decision because context change, new option appeared, whatever. And so you get this very consistent timeline of like how things change, and you start to convey the why and the context So four things in it. Now you'll say, hey, but how do I feel four things?

21:01

Speaker 1: So one of the important parts about ADRs is that you can set your own structure for it. And you can customize this beyond the basics. I mean you need to cover the four basics and I can show you like what we use at October. It has to keep the spirit that this must be something practical to fill. So if you make a like a four-page template, it's like no. You can make like an organization-wide ADR template, like a for a project you can make a specific one. If you are a C LI fan, there are tools out there so you can like Spin out ADR templ uh ADRs from uh template via CLI. Um and the important part about this is that it guides the discussion.

21:48

Speaker 1: So You sort of those discussions start to become on like how will we field information in this? How do we go through the process? And that is what we see while we cook. And so that's something important to consider while we are creating our structure. So you'll see some meta header like on top, like YAML. Um so say hey the status, the date People involved, um you could structure that like deciders, consulted informed, stuff like that Um but it's sort of free form, should be brief. There should be a title that sort of explains what um This decision is about, and I can tell you what we have in our ADR template.

22:35

Speaker 1: So you have this title, context and problem space statement, just like two paragraphs explaining what we what's going on We do have a separate section on decisions drivers and like what we are trying to achieve, like what is the How we will pick a winner before you consider the options like how we will pick a winner? What are we trying to go after The options consider the decision outcome. So we choose X because we wanted this and we accept this As luggage. And you'll see the pros and cons and then pros and cons of the other options. There's also optional parts like validation, how we would enforce this and like Those are more like level two stuff.

23:20

Speaker 1: So if you are going into that's uh just starting with ADRs, you don't need that. That's my take. Um Where does it live? So there is no straight answer for this. A lot of people say different things. Um some people say and strongly suggest that it lives as close to code as possible. So because It's not like business doc. It's not like code and commit history. It's right in the middle, let's say, like in that part. So it sort of gravitates toward lower let's say information part, but you can have it on a wiki or whatever your team usually relies on to retrieve information from a project. That's sort of the habitat of where ADRs live. Like the original author says no, it must be in the repo, but what are

24:08

Speaker 1: what will you do if you have multi-repo? It's like nah Make your own choice, but don't have it somewhere that's inaccessible regularly for a developer. Uh all right, so cooking and IDR. So we will do this live cooking thing, um sort of a food, so Yeah, I thought it was a good analogy. We'll see. Um so the good thing about this part is that it's really a lightweight process. So it's really more about structuring what you're currently doing to capture this information to to decide. So it's sort of like brings a bit of structure but nothing too serious. And you have the positive side of the law of the instrument. If you don't know what that is, it's like the

24:55

Speaker 1: when everything when the only thing you have is a hammer, everything looks like a nail. So if you the only thing that you have is an ADR, everything like you you start to frame discussions into like that form. So and it's good actually. That's my thing again. Short note, you need a kitchen first. So um the Important part here is that when you are making decisions, there is usually context that changes. But there is usually context that does not change. The sort of background noise that's always there, that does not change. It usually takes the form of architectural characteristics, all the elities, you know, like and scalability does not count. You are not school anymore. That's uh given in 2022.

25:41

Speaker 1: But And people say you need to list some, all right. Adaptability, usability, availability, observability So those are the things that are background notes. Like this project is really sensitive to latency. This project is really sensitive to uptime and availability. So that sort of thing should be stated in somewhere. We won't be listing all of those on each decision. It's part of like this common context, this global North Star, global decision driver. Good thing if you are starting with this, you don't have this, you usually have those, but like in your mind, it should not be like vast or complete. Just like go and say, hey, I got this.

26:28

Speaker 1: Architectural feature list from I got from the internet, there are 20. Okay, pick three. You are making two decisions, which one you take and which ones you don't take. And that's super important. Um the case I will present in today and then while we are framing this is like um this we will present in a real architectural decision and this was for a last mile delivery solution. So The retail chain, they have these motos and and bands and people like delivering like Amazon I don't know here delivering packages And so they had this last miles delivery, custom last miles delivery solution being built. It had a React web dashboard and also an Android app made in Angular.

27:14

Speaker 1: The system emits alerts for different types. So this is not part of the ADR. I'm just bringing this so you can understand what follows. So let's get our ingredients to make this ADR. So the first part is we need to articulate the question to answer. And you might say, hey! That's not that doesn't sound so difficult and if you have some uh mileage on you a lot of times once you frame your question appropriately like solutions come more easily So what's really the questions? Sort of throwing there like the seven Y 's, stuff like that, so we can like really get to the core of what we are trying to achieve there. And states the problem context.

27:59

Speaker 1: So why is something undesirable now a problem? What has happened? Like What has changed? Why are we facing this now? Again, short. We don't want to go like overboard like three pages long. Maybe there is some sort of resource we can link. But we won't be reading that in the meeting, and that does not make any sense to go out and fail massively. In our way, this was a in and our dish, this was the context. So We need to send alerts. We need to send push-to-notification false to WEM and to mobile. Um that's done with Reagnate We have at that point deployed the product in the station environment for our client in infrastructure we don't handle, and that was a highly frictionless process.

28:49

Speaker 1: We are uh We are uh we have delay we are behind schedule at this point. We have open risk in the algorithm that roots the packages, that's like the core product And we have a proof of concept of web sockets for the dashboard. So we have this sort of like um notifications coming through Not notification, we have we have this sort of proof of concept uh working. So that's the demise and plus that's when the cook like prepares everything to start cooking afterwards. So one important part here is like Let's choose who will be involving in this discussion. Like not everybody needs to be involved. Who will be responsible for?

29:34

Speaker 1: Like who will make the call? Like is it somebody? That's usually good. A lot of times it's like, no, it's two people, three people, whatever. But let's state that. Regarding who should be there, usually either people that are experienced and can pitch in like options, pros and cons, stuff like that. And also people that is affected by decisions, like developers or like infra people, whatever. And also start to state your decisions drivers. So what are we going to uh strike for. So this is like, yeah, for this decision, this will be important, this will be important. And so we can we have a clear frame or North Star what we are trying to do. That's especially important because it will help you understand

30:21

Speaker 1: the trade-offs you'll be making. So if you ever heard about DASI or alternative RASI or whatever, um Sound this sounds familiar. Uh it's not, it's a cousin, it can help. I'm just pitching this in because people can say, hey, you never heard about this? It's like, yep. But this is more specific, so it's look more like a specific uh causing for architectural decisions. So in our case, what were the decisions drivers? We were high in schedule, and so there were a lot of open risk, so we're like, we want a quick low-risk implementation for these alerts. Latency, but not at every cost.

31:07

Speaker 1: We want latency to be in some threshold. If not, alerts might be useless because they stop becoming alerts It should be easier to configure or operate because we won't be doing them. And last time there was prediction there, so let's keep that in mind. And also low operational cost. I'm listing that here Because that was actually one of the factors that drove our customer to build their solution because they don't want to pay like fees for each package that were like locked in, whatever. So that's one of the parts and and I'm listing that because it's part of the background noise but it's relevant for you to have this issue. So let's go That was not complete. So

31:54

Speaker 1: so and and and then the me the the the gifts are to spice stuff. So first let's go through a decision driver. So we meet, we say, hey, what we are trying to strike for. We pitch options. So hey, I think this can be useful. Great, let's consider that. So you sort of line up some alternatives. So if you're facing one alternative, there's probably no decision to be made. But if not, you'll be listing options and say, hey These are the options and then we start pitching like pros and cons. What are pros and cons? So um important thing about pros and cons it usually helps us to keep us relatively away from bias and that's a good thing usually because we start to be more like

32:40

Speaker 1: objective. And the other thing is that a pro a pro account to be a pro and con must hit some way a decision driver. Like, no, the documents for this library have dark mode. That's great. Not relevant. This is not a pro. It's it's at least unless you will be reading that for two months straight, six hours a day. Maybe then it is because we don't want somebody like losing their eyes or whatever. So I'm not going to go in depth for each of these, but you have this uh for we consider Firebase and WebSockets. So we have Firebase, uh cloud notifications, something like that, and this is Easy to implement, low risk, latency is

33:27

Speaker 1: somehow out of our control. Uh it's free actually. It's third party operated in this case it's good because The operations part did not work well, so we want to keep that out of them. There is vendor lock-in, so this sort of goes to a bit of the background um goals And problems. We have WebSockets, so sort of free as well, it's more flexible. How lower latency, but Certainty, uncertainty starts to creep in and you can see in these pros and cons and again short like concise like boom boom boom boom six eight items Like do they hit the decision drivers? That's something that you will

34:13

Speaker 1: usually talk in a less complete way. So when you're discussing it's like yeah, I think this is good because blah blah blah blah. And yeah but you have to be careful with X and Y and you'll probably cover like four. But when you have to list them, it's like, okay, maybe you can reach six. And so you have a bit better understanding of what's going on. So everything good. So next step is to decide. So you have your context, you have what you're trying to rank options, like the options and pros and cons and it's like okay what you gonna do. So uh you decide. And when you decide you'll be saying, yeah, you know, um

34:59

Speaker 1: This is why we are choosing XY. It's and like it it doesn't mean like formally logically justifies like From where we are now, we're making this decision based on this, and for us it's a better path forward. Um no need to go in depth like yeah, yeah, yeah, we have like Eight pages paper long justification on why this latency won't be a problem. Like no. Just like common sense stuff. That's better than nil. We are currently like none of this information is captured. Uh no need to go into depth. And also you can rely on perception eventually. Like sometimes it's like Sort of even

35:45

Speaker 1: we don't have a and like well we're going for this and it's fine like sort of gut Just state it because people can later on say like yep it was an even thing and they went with this but it was just like a preference and and it's completely fine that's stuff that happens but you need to s state it because things can change down the road and that might impact the the decision In this case we use firease because well um it was an out of the box solution Lower risk, it was less flexible, so we are stating like we are losing flexibility on this decision, but it's fine. We want to get out of the risky situation we are now.

36:31

Speaker 1: This might change down the road, and it's completely acceptable For instance, we are saying this incurs in an acceptable latency. So if later latency becomes unacceptable, we know when we incur in that decision And we can change that. That's fine. But we have this frame of understanding like should we change something? And just the meta header, like what is going on there. Um people disinvolved who they know who they are and uh hi. So some takeaways from what we learned. So first, what we found, so working with companies, different projects Find out we are not alone this project so um in this problem.

37:16

Speaker 1: So this seems to be like this pattern in this industry, so that's bad But that's also good because it's not an isolated thing. So we can start to work in like common solutions that we can adapt and and and evolve. ADRs are great for agile execution, so it really is like low weight um mechanism It helps shape the discussion, so again the hammer thing and it scales so people start to adopt it. There is no like no no we have the ADR master that needs to clear it like People start to get it pretty quick and the most important part is start to doing like exercise like the most important day is the first day.

38:02

Speaker 1: So um They it eventually starts to capture information that again we are losing today. So everything is like an infinite speed up. Benefits, well those are listed in that link. I don't won't be covering so we have a lot we have a bit of time for questions eventually, but uh important parts. It might uncover options you haven't considered, so you'll be saying, hey, ah, we missed that. That's great. We can go back to that decision and consider a new option. Forces you to clarify assumptions. You will be saying in your context, hey, we assume this. And again, going back to the beginning, like if something changes, your assumption changes, you need to evolve Lead seems to consensus, one of the most important parts for me

38:48

Speaker 1: because what happens is all now we have Now we have um uh a consensus on why we reached that decision. Um And other stuff like we can set aside one day or like one hour and like step back what we're trying to achieve, what are the goals of the project of this decision and so forth. That exercise really helps out. Reading ADRs um also helps in different ways New people can aboard easier, but I highlight the third point. So one of the most important parts is like it it can show some maintainer, some developer down the road, if they're changed, they are trying to

39:38

Speaker 1: Bring has already been considered and if it has been discarded, why? Because you'll learn a lot from that decision. Like I think this is good And people say and in the past it has been said no, this is bad because X and say, oh right, and you'll uncover something you didn't know, or maybe it's time to recall that decision. And can be showers justifications for stakeholders. So like somebody comes along, it's like, hey, software architect, whatever, like, yeah, what's going on with this? Ah, yeah, yeah. We make this call. So just enough to uh justify why we did that and 99. 9 % of the cases is enough. Um that's it.

40:31

Speaker 2: We have uh about four minutes for questions, so if you have a question, please raise your hand

40:36

Speaker 3: Thank you. I really enjoyed your talk. I'm curious, how do you get into the habit of making these decisions? Do you include it in your process?

40:42

Speaker 1: Sorry, quickly.

40:43

Speaker 3: How do you get in the habit of making these decisions? How do you get it into your process? Is it a Is it a like a the a sprint ritual that you have, like a set time every so often we have one of these meetings and discuss what we have to decide on, or is it more an ad hoc

41:01

Speaker 1: It's sort like um I have uh an emotion slack. So when people are like yeah discussing stuff and I click Like this might be a good thing to do an ADR about and they start to joke and they use the same emoji. But a lot of the times it's um starting to get teams with that mindset. In my case, I'm usually called in to like, we need help to this for this. It's like Alright, is this like technical help or like are we facing this sort of decision? This so you got a cue like we need to meet that. And and the important part is like In in my experience and

41:46

Speaker 1: our experience, like teams adopt this because they see the benefit and it's a low effort thing. So in the article I was mentioning, they they speak about how it's important to just start because it it it really be becomes I wouldn't say like a natural thing but something that you can do and start to see the benefit and that you um get better at You know, you start picking up mask on memory and so those meetings like go smoother by each time you do. I don't know if it covers the question, but thank you.

42:17

Speaker 2: Any other questions? Uh get to you kid in just a moment. I have one here.

42:25

Speaker 4: Can this be performed on existing mature architecture?

42:30

Speaker 1: Uh yeah, I mean it's uh complementary. So mm in the book they are like pro software architects and they cover how it relates to like what when you what do you do when you have a a staff of software architects working in your organization coordinating across products like How do ADRs work in that scenario? You can, it's uh it's sort of the same. What you usually have is like decision drivers and those sort of things come from regular places or you have this base of what what you're trying to achieve the the architecture characteristics and you have like um what's called like uh um feature-based architectures, something like that when you try to measure

43:19

Speaker 1: things so your architecture is compliant to what was defined. So it will touch those points ADRs in that scenario, but I strongly suggest for that case to go and read like the book that says how it better interacts with in in those scenarios.

43:38

Speaker 2: All good questions, but we are at time. So let's uh give a warm uh round of applause to one of the fashion please.

43:45

Speaker 1: Thank you.

Questions this talk answers

What problem do architectural decision records solve?

They preserve the context, alternatives, trade-offs, and rationale behind decisions that teams otherwise lose. This makes it easier to reflect on past choices, onboard developers, and understand when changing assumptions require revisiting an old decision.

Discussed at 7:12

What counts as an architectural decision?

It is a software design choice addressing a functional or non-functional requirement that is significant to the architecture—more simply, something that is hard to change. Examples include choosing a framework, branching strategy, database, infrastructure, or whether to build or reuse something.

Discussed at 13:15

What should an architectural decision record include?

An ADR should record the context and problem, the options considered, the pros and cons or trade-offs, the resulting consequences, and its status. Statuses can include proposed, accepted, implemented, and superseded, allowing the project to retain a timeline of how decisions evolved.

Discussed at 18:43

Where should architectural decision records be stored?

They can live in a repository, wiki, or another location the team regularly uses, but they should be accessible to developers and kept close to the code or project information rather than hidden in an inaccessible system.

Discussed at 23:20

How do you get a team into the habit of writing ADRs?

Start when a discussion or request signals that a significant technical decision is being made, rather than requiring a separate ritual or meeting. Teams tend to adopt ADRs when they see that the process is low effort and useful; repeated practice makes the discussions smoother.

Discussed at 41:01

Can ADRs be used with an existing mature architecture?

Yes. ADRs are complementary and can document decisions in mature architectures, including decisions coordinated across products and decisions tied to architecture characteristics or compliance goals.

Discussed at 42:30

Presenters

Note: We understand that names change, people change, and bodies change. We respect each individual's journey and privacy. If you have any concerns about a video or need us to remove content, please don't hesitate to contact us. We will handle your request with care and promptly address any issues.

More videos by Juan Saavedra

More videos from DjangoCon US