Architectural Decision Records: The Why and How - Venkat Subramaniam

This talk focuses on the importance of documenting architectural decisions in software development and how it impacts the understanding and evolution of codebases. The speaker shares personal anecdotes about early code experiences, illustrating that without documentation, the rationale behind specific implementations can be lost over time. He emphasizes that architecture involves evaluating trade-offs and making informed choices about tools and frameworks, such as MongoDB, Angular, or Spring Boot. The speaker advocates for Architecture Decision Records (ADRs) as a concise method to document decisions made, detailing why certain technologies are chosen, the options considered, and their pros and cons. By keeping documentation short and accessible, teams can avoid miscommunication and foster better accountability, ultimately improving software practices and visualizing the rationale behind decisions.

We want to talk about um one of the concepts that I wish more of us would do uh when creating uh architectures. Now, before I go into it, uh I want to start with a little story uh that um I think uh it's it's when you when you're young and when you are learning and people tell you to do things, it's natural for us to not like

what we are told you know, not like about doing certain things. And um so this was uh maybe 30 years ago and uh this was one of my first jobs. I was in and um I had implemented a a fairly complex code and once I finished the code uh you know, my boss wanted to review it and we go through the review. I implement a certain changes

and then once we are done, uh I was like happy that this feature is completed and I'm like, "Hey, this is done." And my boss looked at me and said, "What do you mean you're done? You just finished coding it." I'm like, "Yeah, it's it's done. It's working and it you know, it's pushed into the repository, right?" And then he said, "No, no, no, you're going to

go write a document and you're going to describe the problem that you solved. You need to describe the approaches you took and then you need to talk about how you solved it and why you did it." And I looked at him and said "Oh, no, no, this is boring stuff. I I I love writing code. Can I just uh say that it's done and walk away?" And

he said, "No, you're going to write it and then I'm going to review it. And so there was no escape. So I had to write it, he reviews it, and then we, you know, commit it. And then like, okay, it's done. And And of course, you don't realize the value, right? It's like, this is such a stupid thing. It's a waste of time. Well, about 3 months

goes by and one of my colleagues was in maternity uh leave and she comes back to work. She starts and uh a couple of days later I can hear her say "This is stupid." I said, "You just saw my code, didn't you?" She's like, "Oops, I didn't realize I said it loud." And I said, "What are you looking at?" And she said, "Well, I'm looking at this

code and it's not obvious at all why in the world would you do this?" And I said, "Oh, yeah, I remember working on that code. And right now, that's all I remember. Has that ever happened to you?" I cannot even remember what I had for breakfast this morning, right? So leave alone the code I wrote 3 months ago. And I told her, "I don't have a I

don't remember why I did this. But if I look at the code right now, I can I can see why you would say it." Oh, by the way uh the boss asked me to write that stupid document. Have you had a chance to look at it? And she said, "Oh, no, I didn't realize you had a document. Well, I'll look at And then she uh reads the

document and then she comes to me and says "Well, thank you for writing it because now it makes really good sense why you had to do it this way. And in fact, I'm glad you wrote it because I would have probably modified the code to make it better and in the process, I would have probably made it worse because this problem is something that requires a a

different solution than what you would think originally." Well, that's a lesson I learned quite a long time ago. And And sometimes you don't appreciate lessons when you when you're learning. And years later, right? When your bosses are no longer bosses, you probably reflect back and you appreciate it. I wouldn't still tell my boss if I run into him today, right, that I really enjoyed his advice, but

this is just between us, right? Don't ever, you know, say this to him if you ever see. But the point really is that we often want to uh evaluate uh when we when you're deciding on an architecture, what do we normally do? Architecture, this is one of the things to keep in mind. So, creating architecture, you can say, is all about evaluating uh trade-offs. So, essentially, when

you're creating you're constantly evaluating trade-offs. You don't get the luxury of saying, I want to do this, I don't want to do the other thing. That's not some Is audio working? Okay. So, thank you. So, you don't have the luxury of saying, I want this and I don't want that. What you are really doing is you're trying to compromise. You're saying, if I choose this, that's going

to have an impact on this. So, you know, you you're driving your car, you go at a certain speed. If you increase the speed, you're probably going to burn gasoline a lot more. There's a reason why in the US most roads, at least the the way it was years ago, is that a 50 mi mile 55 mph on the freeway. Well, that's because they figured out 50

mi 55 mph was was a speed at which you burn gasoline at a certain level. If you go faster than that, you're going to burn more gas. So, you can go to a place faster, but you're going to burn more fuel to get there. So, these kinds of trade-offs and constraints you often have to deal with. So, so architecting is about evaluating trade-off. But, you when you're

writing code, you are looking at a code and there are certain things that are in the code. So, when you look at a code, you can have a good variable name, you can write good method names, you can write good class names. So, that conveys a certain details. So, a code often may reveal design details to you. I often the design lives in the code. But, what

is not in the code? The code tells you what it is doing. The code even tells you how it is doing. The code doesn't tell you why it is doing what it's supposed to do. The why's are not in the code. You can write a comment in the code that says why you wrote the code. I almost always refuse to have comments that tell me what the

code is doing because I can see it in the code. But, why does the code exist? That can be really useful. But, that's often at the design level. And it also may comment about why a particular code or a function or a parameter exists in a certain way, but an architectural detail is much more broader than what a piece of code is going to do. So, the

question you want to really ask is the following. What is the most important question you can think of when it comes to architecture? I can ask you what's the architecture and you can describe what the architecture is. But, you have to ask the question. So, you could say, right? So, most important uh question uh question to ask uh is why? So, this is the question we need

to always be able to answer. Why are we choosing this? You know, you can look at different libraries and framework. But, often I would ask people "Why are you using Angular? Why are you using React? Why are you using Spring? Why are you using Micronut?" Well, the reason why we are using these tools or libraries or framework, we should be able to explain it. If you are

not able to explain it, it could be because it's because of a bias. It could be because of influence. It could be because they told me so and I have to use it. But it may not be the right choice. And so, to us, justifying the reason why we are doing things becomes very important. How many times have you been in a in a job where you're

looking at something being used and somebody comes to you and says, "Why are you using this?" And your answer often, this is a consistent answer I get from people any company I go to. I will look at something that's complete mess and say, "Hey, why did you do this?" And their answer always is, "Venkat, you should know. I've been with this company only for 1 year. They

did this before I joined." It's always the answer, right? That's very easy. It's like, "Oh, that's not My hands are clean. No, I was not responsible for this." But the problem is, if you can't tell why certain decisions were made, what job are you in? Anybody wants to take a guess? What's your job? If you cannot explain there's a title for it. are a software archaeologist. Right?

So, essentially, that's your job. You're a You're a software archaeologist. What does an archaeologist often do? An archaeologist is often trying to discover what it meant. I was one time visiting a cave and in the cave they had a little board that said, "Here are some artifacts. Here are some arts and artifacts we found." Excuse me. And then they said, "Um this was, you know, created by

people who lived in these caves, you know, you you know, centuries ago. We don't know what they created this for and we only have to guess what they may have meant." And I was staring at it and I screamed. I said, "Oh my gosh, we never changed. This is exactly what I do at work. Instead of artifacts, I look at the code artifacts. I don't know this

guy meant something or this person meant something when they wrote it and now we don't have a clue why they wrote it. So, we are trying to understand why certain decisions were made, but we don't know. It's just a pure guess at this point. But, there's a bigger trouble, though. You're looking at something and you're like, "Why are they doing this?" And you change it only to

realize after you make the change, it doesn't work anymore. And then eventually you're like, "Oh, now I know why they used it." But, that's a lot of expense, lot of effort to change it. Had we known why they used it, then we can ask the question, "Are those situations still, you know, relevant?" If it is changed, maybe we should consider changing it. If it's still the same,

well, maybe we should reevaluate closer to see if those solutions are still valid for that situation because that gives us a reason why this has been chosen. So, aren't comments sufficient? Well, the problem is comments often are too low level in a particular piece of code. And the architectural decisions often are much broader. I can show you a code and say, "Here is a function and here

is the reason why this parameter is of this type and why we depend on an interface here, why we have this coupling. But that's a design concern, not an architectural concern. But I want to tell you why we specifically chose this particular database. I want to be able to tell you why we chose this particular framework. Where do you put that comment? That comment doesn't belong in

any one file, in any one function or a class. So, comments are often not the right way to communicate. Besides, comments are not really as verbose and descriptive as we may need to. And if they are, that's a problem, too. I remember one job I had, and I had joined this company, and most people who worked on the code didn't work there anymore. So, everybody, most of

the people were new to the code base. And I'm reading through the code. I'm new to the company, right? I'm reading through the code, and you wouldn't believe it. They would have comments that were so descriptive. LR things, this is the way it should be done, but PK did not agree. So, we discussed it, and LR doesn't agree. And I'm like reading through this story and story

and story, right? I've read through this for about 2 years at this point. And one day the company said, "Hey, we're going to have a party. We're going to have a social." And we decided to invite everybody that used to work in this company, right? This is a very close-knit community. Uh everybody knows everybody in this in this community of companies. So, yeah, I know this guy

works in this company. We have invited him. So, they're all meeting in this in this place. So, I'm this new person, right? Relatively speaking, I've not seen these people who used to work. And I'm just standing and watching these people talk. And I went to one guy and said, "Hey, are you LK?" And he's like, "Yeah. Do we know with other?" "No, but I've read your comments.

Because I can feel it, right? I can see it. Here is voice. This has got to be LK, which is kind of scary, right? Because you hear somebody and you're like, I know this person because I've read his comments. That is way too much information in comments, right? Don't want that. So, we often make design decisions. We also make architectural decisions. Now, certain decisions are design decisions.

Like what? What should your parameter be? What should your function should be? Which class needs to talk to which other class? Those are design decisions. What are your architectural decisions? Hey, what database should I be using? Uh what framework should I be using? What programming language should I be using? So, these are all a very deep architectural decisions. Oh, we need a messaging layer, but what kind

of messaging tool are we going to use for it? How do we provide a notification of these messages? How are we going to implement it? And do we need to provide persistence for these notification? Those things are architectural decisions you have to make. But, you say, "Did you just say documentation?" Now, one of the problems is in the tur- in in days before Agile development came about,

we used to write a lot of documents. I used to spend my time creating document after document after document. The problem is you wrote the documents, but almost nobody read it. And that is really a problem, because you're wasting your time writing this document that nobody is going to bother to read it. This happens in some places, right? So, I had I was speaking in a conference

and we were talking about this and one lady said, "Well, I have a problem. I work for a boss who insists that for everything I do, I write a long And and it's frustrating. It's a waste And I and and nobody is reading it. "I got a question for you. What does your boss do when you give this document?" And oh my gosh, every Tuesday it's a

ritual. I've got to give him the document. That's fine. But what does he do when you give him the document? And she said, "I know exactly what he does. Right as I give him the document, while speaking, he turns and he files it in his cabinet." I said, "Have you ever seen him remove it from the cabinet?" It's it's it's right only copy cabinet, right? It's not

a read cabinet. And and and she said, "No, he always puts in there." And I told her, "You know, mistakes do happen. You know that, You may stumble upon a old report, you put a new date on it, and you turn it in. It could happen." And her eyes light up and said, "Thank you. You just saved me so much effort because I know he will never

read it. So, I'm just going to put new cover on old documents and start submitting it." And she was ever happy ever after ever after since then. The point is is it is it used? Right? Uh a past president of Cadence once said, "I've never seen anyone write uh read a 250-page document. And if I ever if I find anybody reading it, I'll kill him to get

him out of the gene pool." he said. The point is nobody actually spends time reading long documents. If you're still wondering if that's true, I've got an idea for you. Take a 100 rupees or maybe 500 rupees, whatever you like, right? Take it and just open up the 12th page and put that money in there and give it to the person that wanted the document. Don't say

anything. Just put a 200 rupees, 300 rupees, put it there and give it to them. Just wait for a week. And then when they're in the office, go to them and say, "I'm really sorry. Do you have the document I gave you?" And they're like, "Yeah, sure." And then in front of them, open the page 12, take the money, put in your pocket, and walk away. They

kind of get the message, right? That they have not really taken the time to read it. Because had they read it, that rupees would have been used for good cause already, right? So, so the point is, we get hung up on writing documents that people don't read, and that's pretty useless. But the problem though is, Agile development kind of took us probably in the wrong direction. Not

because Agile development wanted us to do so, but we interpreted uh as so. And we said, oh boy, no documentation. So, we started really hating documentation, we refused to write documentation when it comes to Agile development. But the point though they generally speaking extremes are really not a good place to be in. So, this one extreme, we'll document the heck out of it. The other extreme, we

will create no document. And both of those are really problematic. One of the lessons I've learned over time is, if I don't write any documentation at all, it is expensive for me to make the changes later on. But if I write a heavyweight document, it becomes obsolete, it becomes hard to read, and nobody reads it. So, we need to really you know, strike this middle ground. So,

useless documents should be avoided. So, you don't want to be creating documents that nobody acts has any purpose for. Nobody has a benefit for. So, if you work in a company, and they tell you, you got to create a sequence diagram, well, tough luck. Who's going to read those sequence diagrams? Probably nobody So, you can decide whether it's useful to create these documents, and normally I would

say, who is using it, what's the benefit, and and what are the consequences of writing it. So, avoid useless documents. Large documents are almost never read or maintained. So, the goal is not to write a lot of documentation. I I I more recently worked in a company and I call it death by documentation. So, they would write a document. Only 2 months later, somebody else would write

the same document. Hey, why are you writing this document? Well, they wrote it, but I have to write it. And the worst things they'll come and ask me to review it. I am like, here's my argument. Head is spinning. I've reviewed this only five times written by five different people, right? And they love writing document. The problem is they write document, but they don't get any real

work done. So, all that they do is keep documenting. This is love documenting. That is death by documentation, right? It doesn't provide much benefit, unfortunately. So, large documents really are hard to read. We don't maintain it. We definitely want to avoid it. My general rule is if any document is more than eight pages, So, keep it as short as possible. The goal is not to be cryptic,

but the goal is not to just write way too much that nobody's going to have patience to read it. So, keep them really short. When you keep the document short and up to point, it's easy to write. People are going to read it. We're going to maintain it. So, it becomes a lot easier to work with it as well. So, having said that, this is where ADRs

come in. So, what are ADRs? ADR stands for architecture decision records. Let's tear that into pieces. The first is architecture because these are related to architecture. These are decision. So, what kind of decisions do you make? And records of those decisions. Now, here is a problem we often face. When you want to choose a technology, how do we normally choose a technology? You sometimes choose a technology

because somebody else told you to do so. Sometimes you use a technology because that's what everybody else is doing it, so you're doing it, too. that's a reference implementation you're supposed to carry it forward. The problem is how do you say this is what we chose? There is something that I find enormously valuable and that is if you start writing things down it introduces a lot more

discipline. It also introduces accountability. If you come to me and say, "How do I do this?" Do it this way. Okay, thank you. But there was no accountability. This was pure word. He said it, I did it, and she said it, I did it. But who was there to support it? Three months goes by. Hey, why did you decide this? You know what? I don't remember. I

spoke to somebody and they said do this. Or I I asked them and he said do this. But then I can come to you and say, "Hey, did you say to use it?" I'm like, "I don't even have any memory of this conversation." So there's no if we don't document stuff. But the minute you start writing things you realize you cannot write rubbish and So if you

have to write down, why are you using virtual threads? Hey, I should be able to justify why I'm using virtual threads. If I cannot justify why I'm using what do I put in the document? I'm using virtual threads because I think it's cool. How does How does that feel? If your document says this is cool. Is that a professional document? You're using this because it's cool, right?

That's a fantastic reason to use stuff, right? So this cannot be like I like vanilla ice cream. Like why? Because I like it. That's fine. You can have preferences for things, but this is technology choice, you got to be able to justify it. So, when you start writing things down, there is rigor in it. When you start writing things down, you are going to ask somebody else

to review it. And you are saying, "Does this make sense? Is this a good reason to do it?" And there are times when the reasons are not good. The times when reasons may be obsolete. I may have a certain thought, but you may say, "Hey Venkat, that's no longer valid. This has changed already. So, those are not right assumptions." Oh, thank you for saying it when you're

reviewing it. So, ADRs are a form a form of documenting the decisions that you have made. That's what ADRs are for. Now, the beauty of a ADR is you're sitting in a meeting and you have a new person you hired 3 months ago. And this new person is in the room, there are other people in the and this person who is new says, "Can you tell me

why you chose a MongoDB?" And everybody is like, "You know what? We don't remember." Or somebody says, "Hey, it was there when I joined. I just used it, right?" And somebody else is like, "Yeah, I remember this discussion, but we don't remember why we chose it." is there a ADR that says, "How did we decide to use that particular database?" Oh, yeah, here's a ADR. And you

start looking at it like, "Oh, so here are the reasons why uh we decided to use MongoDB." And it describes those details. Now, what are the details that's going to go into an ADR? So, why why do we need it? There are two reasons why we need it. The first reason you're able to justify why you chose a certain technology or chose a particular decision. There's a

way to justify it. The second is it gives us the ability to review and understand why the decision was made at the time that decision was made. So, it may not be valid any longer, but you are able to understand why the decision was made as well. So, this becomes a nice way for us to say, "Yeah, we we can see what went through these people's mind."

I I was I was consulting for a company. And again, don't get me wrong, right? I'm not saying this technology is a good thing or a bad thing. I'm just making observations here that I've seen. So, I was I was consulting for this company and I went to their VP and said, "I've every project every product in your company is using Java?" And immediately after he said,

"Oh, I can easily answer that question. A while ago, a bunch of people really liked Java and they made sure to ask all the questions for which Java will be the answer, and it became Java after that." Well, that's a clear sign that there was no a formal process because if there's a formal process, you're going to do the do do do do and evaluate it, and

maybe Java is the right choice, but you have a way to document and say, "This is the reason we chose it." So, I must be able to justify those, right? I was um building an application and and I I program in, you know, multiple different languages. I love programming languages in general. But, I was sitting in a conference just like this one and sitting next to me

is was an author of a programming language. And we're just having a good chat, and then the conversation rolled over to the application I was developing. And he said, "Oh, question. What are you using for this application?" And I said, "This is the language I'm using." And he said, "I'm disappointed. You're not using my language, right?" And I said, "Well, do you want to know why I

chose this other language? That's a more important question, isn't it?" And he said, "Yeah, tell me why you chose this other language." And I said, "The was number one reason is the ease of testing. The tooling for testing was much better in this other language than yours, and that's the reason I went towards it. So, I have a clear reason as to why a choice was made,

right? When I have these different choices, why am I deciding one versus the other? I must be able to justify that. And in this particular case, the justification was the story of testing and what it takes to test and how this does this make the testing much better, easier. So, so it gives a way for us to justify, gives a way for us to reflect back and

say, "This is why we chose it." So, over time, we ask why certain decisions were made, and often time, we don't know the But here's the problem. There's a saying, right? Those who do not know the history are condemned to repeat it. That's a wonderful statement, isn't it? That's a code that says, "Those who do not understand the history are condemned to repeat it." So, if you

don't know why certain decisions were made, you're probably going to repeat those to get into the same mess they were in. And if you had known it, you know how to avoid it, so that can be very time-saving and and it can save your effort as well. And not knowing can be very frustrating. You're sitting there and saying, "I don't understand. Why did they make this decision?"

And nobody is around to tell. You sometimes go around, and this is like in the families, right? You go to You go to mom, and and mom says, "I don't have a clue. And you go to grandma. Grandma, why did they do that? And and first grandma will make some stories, right? And then you say, "Grandma, that doesn't make any sense." And then grandma is like, "Okay,

you should really go ask my mom. Thankfully, she's still alive." So, you go to great great grandma and you ask, right? So, this was like a story, right? And the kid goes to the mom and says, uh why are you chopping this turkey before you put into the oven? And the mom gives all kinds of stories, right? And you know how kids are very smart. He's like,

"Mom, that doesn't make any And the mom says, "You know what? I've given you the explanation I can. Why don't you go ask your your your grandma." So, the kid goes to grandma. He says, "Grandma, mom always chops her turkey and puts it in the oven. I don't understand. She give me all these, you know, uh wild turkey stories, but you tell me why this is done."

And and the grandma is like, "You know what, kid? I've done it this way because that's how they did it. Why don't you go ask my mom." So, the kid goes to the great grandma and says, "Uh my mom always cuts this turkey and puts it in the oven. Why are we doing this?" And and the great grandma says, "That's because your mom is silly. In the

olden days, we didn't have ovens that were that big. The only way we can use it to cut it and put it in there. Today, the ovens are big. I don't know why she's still doing it, right? So, the point is if you don't understand why, you could still be doing stuff that This there's this idea called the cargo cult. Uh cargo cult in programming, we have

a cargo cult as well. So, what is a cargo cult? The story goes that in the time of World War II, uh there there was uh Polynesian uh countries, there were indigenous people. These were people living in islands. And they suddenly saw these uh you know, military uh operations. So, they were at a distance because these are like people that are don't belong to their communities and

they were trying to observe these people. So, these military people, what do they do? Uh they land an airplane and the next thing you know, the door opens from the airplane and there's cargo that comes out of the airplane. You know, these big huge boxes and they arrive and they're like curious, what's in those boxes? And then as time goes on, somebody loses one of their shoes

and one of the indigenous people find the shoe and they're trying to figure out what do you do with this shoe because they've never wear worn a shoe shoe before. And they realize and they look over there and they find these people wearing the shoes in their foot. They put the shoes in their foot and my gosh, this is so comfortable. And then they are like, how

do you get these shoes? And they're trying to figure out and somebody says, the way you get the shoe is you got to pray to God. If you pray to God, you'll get the shoes. And they're like, but how do they pray? Well, how do they I mean, we pray, we never get shoes. These people obviously are praying. How do they get the shoe? How do you

pray in a way you get the And then they're again, they send a scout and say, "Observe these people, what do they do?" And then they figure out, these guys are standing there with a stick and they are doing this and suddenly the sky opens and an airplane comes from the sky and lands. And then this door opens and cargo comes out. So, the village leader says,

"We figured this out." And so, he orders people to get some sticks and they keep doing this because you will eventually have this this cargo come and deliver all these goods, right? Well, in programming, we see this a lot. You go to people and say, "Why are you doing it?" "Oh, because I saw her do it." Right? And because it works for her, I'm going to do

it here, too. And this is cargo culting. And and and we do this because we saw others do it, but we don't quite understand why they are doing it. That can be very dangerous as well. So, not knowing can lead to more frustration and to these errors also. Do we accept it because it is what is in place? Hey, why are you doing it? Hey, that's the

way it's been done. So, don't question it. That's the way it is. Well, is this a good reason? Is it a bad reason? Is it the reason still valid? We Do we change it without knowing why it was there? That's a huge risk. You take all this time and you change it and only to find out it doesn't work as expected. And what do you have to

deal with it now? You're like, gosh, why didn't this work? And somebody says, now you know why they had it. Well, we don't know why they had it, but what they had worked, but the change did not help us. So, by documenting it, it's like, here are the characteristics we had to meet. And because we had to meet these characteristics, we chose this particular solution. Now, you

can say, wait, are those characteristics still Have you have Have you had a change in characteristics? If we change the then we will have to change what we are doing because that's no longer the case. Or if the characteristics are the still the same, is that still a good solution? Or has there been a change in the technology? Maybe there's a simpler solution or a better solution.

It gives us an opportunity to evaluate really So, do we change it without considering other options? How many times has this happened? I had a a client. We were developing this application for them and their requirements said, use this particular library. That was a requirement. You will use this library. by this time, I've had about, I don't know, five or six years of experience doing stuff. You

know, they say, right? Experience is where you can make your mistakes before your luck runs out. So, I had experiences before where I remember I had gone in and used a particular database which implemented a brand new feature. And this new feature, right? I was this young uh you know, programmer with no experience. And it's kind of funny, The the lower your experience, the higher your confidence,

isn't it? So, I am like, I don't know anything. So, I've got a lot of confidence. So, I went in there and like, super cool. I saw this feature. I went to a training. I know how this works. Boom. I made the change to this entire application. And and it's done, right? And I made the change, ran a few tests, it seems to work, commit. And walking

with confidence, yay! I I was the first one to implement this feature ever because it's a new feature in this database. Well, 2 weeks goes by and one of our testers comes to me and says, I was using this particular uh code and it I performed this operation and it entirely corrupted the database. Gone. Poof." I'm like, "What do you mean it corrupted the database?" No more.

You cannot access it. It it's it's failing. And I'm like, "Serious?" Let's take a look at it. And we get a database from the backup in the test environment, do this operation, boom, gone. And we are scratching our head. And I'm like, "Okay, so what do you think is the problem?" And this is a very good tester. He said, "Aha, I know you're going to ask this.

So, I put the old database before you added the feature and I put put pulled the old code. I'm performing the same operation. Notice it's successful, no corruption. Now it's the same database. I'm taking your new code, I run it, it's corrupted. What's the problem? And I'm sitting there entirely clueless. You can imagine, right? You're sitting in front of a code you have written, you don't know

why it doesn't work. how do you debug this? I'm sitting and breaking my head. And you think things cannot go any worse, right? You are sitting there staring at the code, and everybody is waiting on you because this has to be working, and you're trying to do things, and that's when your boss comes in. Hey, how's it going? What do you tell your boss when you have

no clue? You're like, shut up. I'm trying to figure this out. You're not helping me, right? And And what is the worst thing you can tell somebody? Venkat, if anyone can solve it, I know you can solve it. Don't, please. Be quiet. Don't patronize me, right? It's not working. I have no clue why it's not working. It This is not helping, right? And about a 3 weeks,

you can imagine, 3 weeks. And I'm going to my boss and saying, you know, I really need some help. Can I send this code over so the people uh in the database company can look at it? Oh, you want to send the code? That's what I just said. Um we have to go talk to the attorneys first. We got to get a legal document signed because it

involves IP. So we got to get that signed, then we got to have an NDA signed from them. So by the time it's over, it's going to be a month before we can get this done. So I learned my lesson the hard way. after 3 weeks, I get a call from the database vendor because I've been calling them every day and talking to them and the guy

calls me and says, "Hey, I got some news for you." I'm like, "What is it?" "Oh, I'm really sorry to tell you, we found a bug in the database and we just fixed it." I'm like, "You're kidding me. So, my code has no problem at all. It's your problem." It's like, "Yeah, it's our problem but we won't admit it." So, it's a bug fix, right? It's a

patch. And and okay, I'm getting myself. He said, "We'll send you the tape." So, he's sending me the tape. Now, I got to put the tape in there, run the tape and install software. Yeah, for those of you don't know, we didn't have we download by getting the tape delivered by courier. And then you put the tape on a tape drive and you spin it. That's how

we install software back then. So, I So, fast forward a few few years later, right? I'm working with this company, you will use this library. That's in the contract. It's in the contract. And I'm like, "Aha, I've got some scars in my body. I've been through this path before doing something without knowing what it's going to do." No, I'm not going to do it. So, I implemented

the code using an older library that I'm familiar with. And I told my client, "You know what? I'm going to I'm going to make progress. I need to move forward. I'm going to use and we're going to order this particular It needs to be shipped to us and and we don't know when it's going to arrive. It may be a few weeks before we get it. And

when we get it, at no cost to you, we'll swap this out and I'll use the library for you." They're like, "Okay, if you're making progress, that's good." So, about a month or so goes by, we eventually get the software. We install it. This time it was an upgrade, by the way. This was a floppy disk, not a tape drive, right? Things are progressing a little bit.

Uh for those of you who don't know what a floppy drive is, that is the save symbol that you see in your applications these days, right? And so, put the floppy drive, install it. And something tells me, you know what? Nah, you've been through this path before, don't trust it. So, I left my application alone and I wrote a separate uh prototype, a little example. And all

my example did was draw about a 10,000 circles. That's all it did. Why? Because there's a visualization library. I drew about 10,000 circles. I used the old library to do it and I flipped over to use a new library. And now in the new library, you can literally watch that circle being drawn. You can just do this and you can see it being drawn. It was doggone

slow. I'm like, what am I doing wrong? I spent 2 days trying to debug, couldn't find I called the vendor and said, "Excuse me, I'm using your library. I don't get the performance with it, but I know another library is doing well. Could you please take a look at it?" Yeah, if you can send me the code. Yeah, here you have it. There's nothing proprietary about this

sample, right? So, when you isolate and create an example, you can show it to anybody. It's drawing stupid circles, nothing to do with my application. So, a day goes by and they called me on the phone and said, "Who asked you to use our library?" I said, "Why? What's going on?" "This is not the use case at all. This is kind of stupid. This is not the

intended purpose at all." And I said, "Could you put that in an email and send it to me?" "Yeah, you are stupid. That's easy to write email, too." And they just emailed me and said, "This is not the intended purpose. Why are you using it for this?" And I had to go to the client and say, "I'll I'll change this one-time port, but if I do, here's

an example of the performance you're going to get." And guess what they said? "Oh my god, no. The old library is good. Don't use the new one." And I said, "Could you please tell me why you had that in the contract?" You know what their answer was? "Oh, somebody told us this is a cool library." I'm like, so that's how you do things. You put that in

a contract and you wasted so much of my time. And and your money, because you're paying for my time, right? And and and if only we had taken a disciplined approach, you're not going to say, I heard this somewhere, and so we decided it's going to be the one we're going to use. That is a risk you want to avoid. So, we want to evaluate options. But

you want to know why you are evaluating options. You want to know what options were considered, and among them, what did you choose? Why do we need to do this? How many times have you seen this, right? You're sitting at a table, people are talking, and there's always this one person, uh if only you had used this other database. Oh, here we go again. But why? Because

that's their favorite database. Or how many times have you heard people say, oh, if you only used Groovy, if you only used Kotlin, if you only used Scala, if you only used C#, if you only used Python. Does anybody say if you only used PHP? I don't think so, right? But anyway, so I digress. So, the point is, oh, if only you If we had looked at

the options, you can say, yeah, we evaluated that, too. So, don't say that anymore. We've gone through that. Oh, maybe we didn't. The documentation will tell you that. without considering the consequences? Well, there is pluses and minuses. You chose a technology, but there are consequences of choosing And what are the downsides? Are you aware of it? And if you're aware of it, you work through those consequences.

And and you didn't choose without knowing it, and then you're not suffering because of the choice that you And do we change it again without nailing down the reasons for the change? So, these are all high-risk. And in companies that don't have a they make all these changes and they suffer the consequences of that later on and that's what ADRs can help. So, what goes into an

ADR? I'm going to write an ADR, but what should I put in an ADR? Remember, you don't want this to turn into a 50-page document because nobody's going to read it. You don't want it to turn into a Oh, here's an ADR. We chose it. Thanks for listening. That's not going to help you. There's got to be enough details. So, what do you put in an ADR?

The first is a title. So, give me a title for an ADR. What is an example of a title? XYZ module. what database did you choose to use? Why did you not use Oracle? Why did you go with the MongoDB? Or maybe you chose a graph database. Why did you do so? You need to be able to describe that. Maybe another one. Uh you could say library

for notification. What did you choose for the notification, uh you know, as a library? You could say, "Hey, here's what we chose for a parser." Which parser did you choose and why? These could be the reasons, right? Or we decided to use Spring Boot. Well, tell me why. Oh, we decided to use Micronut over here. Tell me why you chose a Micronut. Uh but the framework for

the back end could be your title. Um the framework for the front end. How many times do you see this? You go to companies and they say, "We use Angular." I always say, "I'm sorry to hear that, but why?" Why did you choose Angular? And we don't have a good answer. Oh, it's because that's what they told we should use. Why did you choose React? Why did

you choose Svelte? Whatever you chose or plain vanilla, you know, JavaScript. Why? front-end framework, right? That's a That's a title. Decide what you're going to use. Provide a context. The context tells you the details you're going to consider in choosing this particular technology that you're going to use to implement. So, describe what is the context? We Our database requires to store application-specific data. It does not have

to choose enterprise data. Or in another case, this database is supposed to keep enterprise data. It is expected to be used by 200 different applications. That's your So, you describe the context as to when you're going to choose this becomes The status. What is the status? Complete. Evaluation. In review. Proposal stage. Draft. What stage is it in? That's your status. Creation. We're just creating it. No time

out. We're good. So, uh essentially, um we are deciding this, but here are the you know, it's initial document. Or it is a document we just created, but we're putting initial data into it. It's in a review stage. It's in a completed stage. it's in a deprecated stage. We no longer are going to use this because we have moved on from that. No longer valid. That's 5

years old, right? Whatever it is. What is your decision? Rejected. We're not going to do that at all. Accepted, approved. Whatever the decision could be, right? You're documenting the decision. And the options considered. We decided to use an application database. But, what are the options you evaluated? Oh, we evaluated MongoDB maybe. What are the document databases you Put the list of things you evaluated. Did you prototype?

Did you try between these solutions? And talk about it. And and that's your uh considered options and the pros and cons of these options. So, you're saying we took the time. We evaluated these three things. And then decided this based on that, right? That's what you're saying. And what are the consequences? Hey, if we use this document database, the consequence is you cannot have arbitrary application in

your enterprise just leaking and start using it. It's not an enterprise data, it's an application data. So, this is for internal use only by this application. If the data is needed externally, you got to find a way to export. That's your consequence that you're writing as well. What you want to put in your ADR is the decisions you made, the options you considered, the reason why you

chose one or the other. We and not Angular. Why? Because we do not need a heavyweight framework on the front end. We only want a lightweight framework or tool. Oh, we decided not to use maybe a local storage on the client side. And here are the reasons we chose to implement our own solution. And whatever the reason is, you're providing those details into an ADR. What does

not go into ADR? You're not showing code. You're not giving fine-grained details that are not relevant to the decision you're making. You want to keep it so short and easy to work with. So, you can use some tools for the ADR. There are few different tools in the market you can use. There are some open source tools. But, what is important is make sure your ADR is

versioned. What when you look at it, this is version 1.0, this is version 1.1, this is version 2.2, whatever it is. Provide the versioning on them. So, because we keep improving based on things. Why? You are saying, we decided to go from we decided to use a springboard, but now there's a newer version that says, we decided to use this particular version. Even though it's not the

latest version, we're using this version because we'll talk about what other libraries depending on, it wouldn't work with these other libraries with a different version. You're documenting those. But, it must be easy to access it. If you say, do we have an ADR? The wrong answer is a shrug. I don't Well, we should be able to quickly look at it. So, a lot of times, I'm a

big fan of storing ADRs in your Git repository. Guess what? It gets versioned automatically when you commit it as well. And that becomes a lot easier to to look at it. And find whatever tool that works for you best to visualize it and to edit it. But but if it creates a document, you can store that into your Git repository. You get the best of both worlds.

You're able to view it with the tool, but it gets committed to your Git repository. You can pull it in, you can version it, you can save it, you can back it up, and so on. Use whatever is the standard in your organization. The closer you are to the standards in your organization, the better you are. Because otherwise people, you know, tend to use it much better

when it is. So, you can use a few different tools. There's a tool called log for brains. Log for brains, you install it, you just run it, it pulls up a ADR and allows you to create ADRs and allows you to edit it. Easy to use tool. Takes you less than 5 minutes to start using this tool. Nothing really complicated. You just do log for uh for

brains in it and then you can ADR new. Allows you to create a new ADR with it. It opens a browser, gives you a visual into it, and it saves everything into a file, a directory structure. Typically, I will put the directory structure into my Git repository. Off you go, right? So, the tool can help me to visualize it and edit it, and then I do a

Git commit and it's in my in my Git So, you can you can look at it, but I want to talk about a few different tenants, do's and don'ts of ADRs. First, ADRs are immutable. What is the benefit of being making it immutable? If you make it mutable, you change it, now you lost the original decisions that were made. So, you should never mutate an ADR. So,

your ADR is there. You are saying, "No, you know what? That's no longer valid." No problem. The deprecated. Don't make any changes to it. Create a new ADR, which then points to the old ADR. There's a link. So, when you go to this ADR, you see the decisions here, but you know what decisions it replaced by following the But the original link is not mutated. So, you

don't say, "You know what? That was decided, but we don't know why because that's gone now. They changed it. So, except for changes in the status and fixing typos, that's the only change you're allowed. So, can I change an ADR to change its status? From in progress to uh in review or whatever that is. And to fix typos. But once you are done, you seal it. You

make it read only. And you can duplicate it, but you cannot Su- superseded with new ADRs when old ones are no longer valid. But you don't create a new ADR by changing an existing ADR. You create the new ADR and provide the link to the old ADR so we know what it is superseding in this case. And keep it short. We talked about this earlier, right? Keep

the ADR short. And keep it in plain text. What's one benefit of plain text? Any ideas? A- A- AI? People don't need any tools. Love it. You can grep. If you want me to find stuff on your machine, I just do a grep. It's so easy to find, easy to locate, isn't it? You can have tools that can look through it. You can view it in any

different editors. It's very powerful, right? This is one of the recommendations from pragmatic programmers. Keep your stuff in plain text. If you ask me, where do I keep my uh text? Not Word, not Pages. It's literally plain text files. I can format it any way I want to for a presentation purpose, but I can use tools to go and grep it, to parse it, to deal with

it. And all the Unix-like tools, I can use it on it very easily, right? It's so easy to search as well. You number them sequentially uh along the way, so you have a reference number to go look for it. Becomes a lot easier. And you can you need to keep it in a version control. Uh your Git repository doesn't have to have only code. This is fantastic

to put And so keep it in your version control So we talked about the the reasons why do you want to create it? And this really comes down to And when you have the discipline, I just got an email a couple of days ago from somebody said, "My company is doing this. What do I do?" I'm like, "Write a ADR." Because the minute you start writing an

ADR, you're not doing things because somebody told you to do so. You're doing because you're able to justify. You know what? What they told you to do so may be a good good idea. But you are able to justify it. That's still good. Or maybe that's a terrible idea. You're still able to write the reason for it and why you want to do something different. That becomes

a nice way to communicate that as well. So so it's as much as we hate to write detailed documentation, this is a minimalistic documentation that can give us a lot of value. And and in all honesty, ADR is not just for architectural decision records. ADRs can be used for other decisions we make in our lives, whether it's personal or project-related, company-related. You could be running a business.

You could write descriptions as to why you chose a vendor. Because what happens 5 years from now, you're sitting and talking to a colleague, "Well, you know why we chose that?" Well, because we documented it. Can become a light nice way to look at it. Minimum documentation takes us a long way. Hope that was useful. Thank you. That's all I have. >> [music] >> Hey.