Hey, a quick message, for those of you who are listening to this episode on Spotify, I have a small favor to ask Spotify. Now allows mobile users to rate podcasts, I would really appreciate it. If you can take a quick, pause to go to the technique Journal podcast page, and leave your favorite show. Your best rating on Spotify. It will help me a lot to get this podcast to reach more people on the platform. Thanks a lot.
What if we write down the single decision, the single architectural decision, write it down the truth. A simple markdown, very simple kind of text file. What if we keep the format very straightforward in the style of a pattern? You know, if we describe the context of the world, the forces that are play, maybe their business courses or technical, they could be political. These are the things that are kind of acting on our decision, what it is that we're going to do.
And then as a result of applying this decision, describe the consequences. So at the Navy Yard really intend nutshell, really simple, text file describes, the context, the decision, in the consequences of that decision. Vision. Hey everyone. My name is Henry Surya, we Robin.
And you're listening to the technology, you know, podcast the show where I'll be bringing you the greatest technical leaders practitioners and thought leaders in the industry to discuss about their Journey ideas and practices that we all can learn and apply to build a highly performing technical team and to make an impact in your personal work. So, let's dive into our Journal. Hello again, my friends my list.
- welcome to the technology. Now, podcast the show where you can learn about technical leadership and Excellence from my conversations with great thought, leaders in the tech industry. If this is your first time listening to tackle a journal, subscribe and follow the show on your podcast app and on LinkedIn, Twitter and Instagram. And if you'd like to support my journey, creating this podcast, Please Subscribe as a patron at technology.
Another death / Patron. My guest for today's episode is Michael killing. Michael is an experienced software engineer. Stop by architect and the author of design it in this episode, Michael shared in depth about architecture decision record. Also widely known as a Dr. He first shared his story of discovering Adia before. Describing what inedia is Michael then, share the objectives and benefits of using idea to record architecture decisions and explain the key Behavior changes.
We can observe when we practice ADR towards the end, Michael shared a few practical tips on creating and updating a They are some patterns and anti-patterns, he observed from his experience and suggestions on how we can practice Adia effectively as a team. I really enjoyed my conversation with Michael learning in depth about ADR and some practical tips we can use to practice it more effectively.
And if you also find this episode useful, please help, share it with your friends and colleagues, who can also benefit from listening to this episode. I always appreciate your support in sharing and spreading this podcast and the knowledge to more people. Let's jump to my conversation with Michael after hearing some words from our sponsors. Mental well-being is a silent pandemic.
According to who depression and anxiety caused the global economy over one trillion US dollars every year, it's time to make a difference, learn how to enhance your life through a master class from Founders well-being. And my good friend, Sandy brow on mental Wellness, visit Founders well-being.com / Master Class to enroll and enter tlj 24. 20% discount be a better version of yourself and make an impact. Today's episode is proudly
sponsored by skills matter. The global community and events platform. With more than 100,000 software professionals here members. Can organize their learning experiences around the technology topics. They care about most you get on-demand access to their latest content thought, leadership insights, as well, as the exciting schedule of tech events running across all time zones. So by the devops our data science is your bus or you are fan of functional programming or all things Cloud.
You can make real connections with people who share your interests head on over to skills method or Cam to become part of the tech community that matters most to you. It's free to join and you will find it easy to keep up with the latest tech Trends. Everyone welcome back to the new episode of the Attack original podcast today, I have with me someone named Michael Keeling. He's actually one of the four leaders in the tech industry. He has written a number of
books, including design method. Today, we'll be talking a topic which I'm very interested in, which is architectural decision, records or some people know as a Dr. So Michael, today, I'm very, very pleased to have you on the show. So, looking forward for this conversation. Awesome. Yeah, thanks for having me, Michael. I always like to start my conversation by asking my guests to share more about themselves, may be telling the highlights or Turning Point In your career.
Sure. You have a bit of a history so going way back. Graduating from college women marry with a computer science degree kind of a classic I guess, computer science math, set up getting into the software industry that way. The one thing from that degree that I was in the program there, I took a software engineering class my senior year and that was like, Far and Away.
The most awesome class. I took probably the one course that stuck with me that I find myself applying after I got out into the real world, my first job working for US Department of Defense, Contractor there, I had the opportunity To work on what was called the Aegis modernization project which probably nobody knows what I'm talking about with that.
But it was probably one of the largest model-driven architecture projects around certainly at the time, which is really cool opportunity to see these model-driven architecture. Model driven engineering practices. Firsthand on are real complex, distributed Mission critical system, the stuff we're building was shooting missiles, things like that. So pretty intense.
So from there went back to University for software engineering to Carnegie Mellon but which is what brought me to Pittsburgh where I am. They still that Carnegie Mellon had the opportunity to take some cool courses and meet some awesome people, including Mary Shaw and David Garland did some reading courses with them and semester or so research with David and that was kind of what eventually led to the book design it. So a lot of digging into details
there. Yeah. And since then been in Pittsburgh working for a local startup that was acquired by IBM and then within IBM, we were like reacquired, I guess by Watson. So working for one of the biggest companies around, I guess. At that point. Ain't got in pretty early, not too early but fairly early on the micro services and Cloud Tech Stacks. I was really an exciting time to be doing all that machine
learning Ai, microservices. And then since then, in the past four years, I've been with a fintech called keaw be working in a really big companies. Great. But I felt like it was time to get back to startups so that's why I left and eventually mineral way back to a small company. So it's been quite a journey. So you started from US Department of Defense to startups to Big corporate Batman back to start up, thanks for sharing your journey. That thing is really
interesting. So throughout your journey, I think you discovered this thing called architectural decision record. Oh, let's call it short ADR so maybe tell us more how was the story? How did you discover it and how you've been a prominent supporter of that, I guess? Yeah. So back on my IBM team. We were fairly small team, a
really young team as well. So I was one of the more senior Engineers on the team, but most of the seven or eight, Purrs were right out of University. So maybe one or two years working in a professional software development I guess as I briefly alluded in my story, the beginning you know we were
getting into cloud-based. Microservices we're getting into AI we were getting into cloud-based Technologies, search Technologies, the AI everything is moving really quickly and we're struggling with some of the basic knowledge, sharing basic design principles things like that. That I think a lot of teams struggle with but with us being fairly young and then really in a bit of a pressure grinder, there was a lot of pressure to deliver.
Her and moves quickly at the time with early days of Watson. That's the situation I'm open and looking for any kind of new techniques to bring my team for getting us to think more about architecture. Think more about design. That's when I came across, this Twitter thread, one day it was net price sharing a tool that he'd written for recording. This thing called the adrs over the command line. Just a very simple command line tool.
And like okay this sounds neat what are 80 ours right dig in and I find all this cool stuff that sounded really great. So brought that back to my team. Mmmmmm. Hey, found. This thing called a TRS to give it a try and of course, my team is raved like, yeah, let's do it. What city are? So I had to teach them all that. I guess learned myself because it was my first time with that. I guess that's the discovery and then bring it again to try and solve some problems.
So, maybe in the first place for people, maybe who may not be familiar with this thing called ad office. Maybe what is the definition of ADR? Is there a good way to summarize?
What is an ADR? Yeah, so the cool thing with a DRS, the Other way that we practice today comes from this blog post by Michael Nygaard. He wrote the release it book which I always think those are the companion book to my have design it. So he wrote this blog post that kind of describe this experience report this idea that he was playing with which was okay. What if we write down a single decision, the single architectural decision.
And what if we do it, right it down, it's just a simple markdown, very simple kind of text file. What if we keep the format very straightforward in the style of a pattern like a design pattern from Christopher, Alex? Under, you know, if we describe the context of the world, the forces that are play maybe their business horses are technical,
they could be political. These are the things that are kind of acting on our decision, what it is that we're going to do. And then as a result of applying this decision, describe the consequences again, very like, how does the world change after we've done this decision? But could be trade-offs? It could be quality attributes promoted. It could be new risks or benefits, so that's an easy are really in a nutshell, kind of in its Essence, really simple, text file.
Describes the context, the decision, in the consequences of that decision. I think the real cool part. The thing that was really different because design decisions, architecture decisions. They've been around for probably five six years. At least the study of architecture decisions had been a focus in the research area for a number of years before nine
guards. Blog post the thing that was different though was keep it simple and then put it in the Version Control repository put it right in your git repo next to the code. Those two things really different than what anybody in the architecture community. At least have been talking about up to that point. Point. So I guess there's a long answer coordinate ER is as we dive deeper later on, if I can just summarize in a little bit it is like a simple text-based
decision, right? That's that you store in Version Control and you kind of like capture single decision or it's not like the very overarching architecture document that could be how many hundreds of pages long and it captures three things context. What is the context when you make the decision? And the decision itself, and the consequences may be the trade-offs. Maybe the few things that you consider during the discussion
and you decide. And then you capture, what are the consequences of the decisions. So, thanks for sharing this in a good way, right now summarize format so people should consider a Dr. But what is the true objective of it? Is it just to capture decision records for people to refer back maybe in the next few years? They forget what they did and they just look back. Or is there any other different objectives that you think Adia could help videos are great for capturing those decisions?
And yeah. Yeah you're right. That's one decision to the time which is really amazing and Powerful because one decision is easy and then you just do that every day and then you look back. And next thing you know you got 30 40 pages of documentation of all these great design discussions that have happened over the past however, many months and that's great. Like capturing these design discussions and kind of describing the rationale for the design is really important.
But what I really like about a DRS and the thing that I think is actually even more important is how it facilitates that discussion about design and it really puts design kind of at the Forefront from Senator. So it's kind of putting your team in this amazing place of being, I guess, where you're talking about design, where you're talking about architecture, that's really where the magic starts to
happen. Recording the decisions is great, but the fact that you're coming together as a team and talking about them and really focusing on that is even better. I don't know. That's me, I think that's even more important, perhaps, than the decision itself. So, yeah, I think you brought these good point about facilitating, the design. Maybe the discussion is self and the decisions. So not many engineers in the team, I think would Could be involved in traditional
companies, right? They rely on architect, some architect teams or maybe some senior engineers in the team to decide for them and to come up with all these design decisions. But I think I like what you mentioned is that when you have this kind of probably Cadence or maybe practice together in a software engineering team, you kind of like spread the
knowledge about good design. You put it in a phrase which makes good design inevitable in the team but maybe tell us more why every software engineer needs to be strong, in design and architecture. Us traditionally again, like I said, in some companies they rely on some senior Architects or software Engineers to make the decision for them, right?
Yeah. So a lot of times, I guess a lot of things get to this unfortunate state, where architecture is done by somebody else, somebody else somewhere in the organization, you know, the so called Ivory Tower. Architect, I just hate that term so unfortunate, right? But 80 ours, it brings things that are very distant architecture. Somebody else's problem. It helps bring it closer to home. I think that's important. Orton for a number of reasons, a big one being that it's empowering.
The fact that these 80 ours are close to the code. They're kind of simple text files that it's the team who supposed to be writing that than owning them. Suddenly, you're giving agency to the team to own their own architecture. And to be responsible for it, which is super powerful. This is important, because it's easy to make mistakes with architecture, especially the cloud-based systems that I've traditionally worked on. You might have a perfect design, something that's implementing.
Exactly, the architecture that you want. One completely unaware could unravel that entire architecture. So, I've had cases where someone unbeknownst unaware that perhaps there were certain like layers in the architectural. They would come in and buy lead those layers and then in the process incur tremendous performance penalties that could like increase the cloud costs, the compute costs, things like that or introduce instability in
some way, purely by accident. But you know bringing the EDR is closed. Now it's your responsibility as a developer to kind of be aware of these things and to think A little bit more carefully about what the architecture is and to follow it. Probably the biggest thing with all that is being empowered, you're able to move quicker, you're able to be more Nimble, the bit more agile.
So you're not waiting on other people to make decisions until you what to do, as the developer has the architect, wearing both of those hats, all those things, you could to make the call Rich, your helps you to hopefully move a little bit quicker and be a little bit more agile as a team, which is another fantastic outcome. I think, I think they are also a
couple of things, right? I know that some companies practice this, I've Tyler architecture and things like that producing, hundreds of pages of documents. But they are also aspects where some teams most likely in the startups. They don't actually capture those design decisions. So, tell us more about the danger situation of doing this practice. Not capturing anything down. Yeah, so this is a big discussion, a couple of weeks ago. I was at my first in-person conference since before the
pandemic, which is great. We were chatting about the importance of rationale like with architecture using Fine structure in the code, you can see it. Sometimes you can recreate it. You can kind of make a reasonable sketch based on what you see in the code. But recreating what people were thinking. At the time, they made those decisions is kind of impossible.
I guess there's the chesterton's fence, Parable, which approximately goes you're in the middle of a field and there's a fence in the middle of the field and you need to remove this fence. You want to remove it but it's here. Somebody put it here for a reason. So you kind of have to make a call. Was this thing here for a reason can Through the fence, or maybe it's not there for a reason at all, and it's perfectly. Ok to delete.
So, getting back to code for teens, who, haven't reported design rationale, who, having kind of written down, really any documentation that all? That's what we end up. Seeing a lot of, right? You can recreate the structure, you can see the fence but you have no idea why it's there how it's safe to change. Whether it's ok to delete or not. Now we're going through a lot of
that right now. So with a startup company growing really fast, we've got a lot of foam and not everybody is around anymore to explain exactly how the code got to pee. The way it is. So I think there's any finer appreciation, perhaps things like a DRS. So you mentioned about people leaving the church under retention in many companies. This is common, right?
So people come in gold and I think the danger of not capturing the decisions like you sometimes will probably pop under white such things happen in the code and use really can't tell whether it's safe to delete it, safe to refactor and things
like that. So maybe when we have a Dr, at least we have the context again, coming back to the That you mentioned the context and why decision was made and is there any trade-offs are consequences when the decision was made at that point in time I think when I read some of your articles as well I think there's one thing that I also picked interest in so we know that a dies, the good practice is to capture it along with the code in the Version Control in your article.
You mentioned when the distance between developers and design is too big. Maybe, for example, you have like a separate document not in the source control. Developers perceive design as Having little value. So tell us more why you have this observation? Yeah, so it's back to that idea of the extent of the other,
right? So when architecture is maintained and other documents or you know, in a different knowledge, repository of some kind, it kind of goes out of sight and out of mind, at least in my experience, it becomes a template that you just have to fill in.
Because there's a policy that says you have to fill it in, not necessarily something that you really care about or try and take ownership over, bring the heat ERS into the Version Control. Repository, it creates this Asian. There's this idea of in psychology of an association principle, so things that are
close together. If you value, one of those things and if you can associate other things to the thing that you value, then you'll end up liking all of those things that are kind of associated with it. So this is like a common sales technique. You'll see people who liked this
movie. Also liked this product, they're trying to create that Association to bring you in to get you to like this other thing we could effectively do the same thing with design through a DRS for developers if you highly value the code and if the Code is the number one most important thing. Well, code is important. We put the code in Version Control. That's where all the important stuff goes.
Hey, look at that. Let's put the ATR is in Version Control. It's like, okay, well since it's in Version Control that it must also be important to. So we've kind of created this association between design and code that at least gets the foot in the door. It gets the conversation, started about the importance of design. So many developers who are Skeptics architecture. Somebody else's problem, not my problem. Bring it in closer helps to at least kind of show that there is value here.
And you captured is nicely. So things related to this, practice right Association techniques were developed, a start to Value architecture, decisions more. And I think you observe, therefore key Behavior changes. If we start practicing ADR more frequently, as part of the team culture, maybe can share more. What are these key Behavior
changes that you observe. Yeah. So once we kind of create that Association and once we get developers, kind of talking about design and being willing to think about architecture, more actually, give these ADR things to try a couple of cool things. Start to happen. One of the first important things is building up kind of this, I guess almost social proof. So the most important person writing an ADR. If you're trying to bring a TRS and your team, the most important person is not you.
It's actually the next person. If you're the only person writing edrs, nobody's really going to pay much attention but as soon as a second person starts contributing, that's got power. So now it's not just one person. We've got a group, the starting to form. So now you've got a lot of people were saying, btr's are important. Design is important, so that's
one kind of area. Other people writing a DRS and that starts to kind of change the behavior little bit like oh everybody else is doing it, maybe I should do it. The next thing is the fact that these 80 hours are written down and then we rephrase them is important to wonder saying the decision part, we're saying, we will do XYZ, we will introduce a data layer and it will be the bottom most layer. Only the business layer is allowed to use it, maybe that's
your decision. So you write that up, you write it down. You have other people on your team, review it through your pull request process, may be that It is, in a way. Forming a written commitment. It's like a promise. We made a decision. We will do this thing that we've decided because it's written down. It starts to form this Bond, almost like your word is your bond.
You said we're going to do this thing and now you want to be consistent with the promise you made, which is another one of these psychological principles consistency principle. So what that ends up doing is teams feel more compelled almost to follow through on the designs that they're creating so we made a decision, we've written it down. Read it. We told everybody we're doing this. Now we're actually going to do
it, which is pretty cool. All this kind of leads to building up more and more support I guess for this idea that hey, we're the kind of team who thinks about design where the kind of team who writes down decisions before we make them kind of self-identity, almost of the individuals on the team starts to change that itself, becomes almost reinforcing idea, which is very powerful either. There's a lot of really neat mechanisms built into this little tiny text document, which
I think is really, really great. And you mentioned, like, coming back to the explanation. You did idea. So, the real value of ADI is not just to capture the design in that position control, but actually, you will transform the developers in the team to start, thinking more about design, maybe they will turn into architects in the team, right? So everyone will also become an architect because they're like
making the decisions together. Maybe the overarching goal is to start changing the team culture themselves to think or care more about design before they actually jump into the code and write the code. I think this kind of thing, culture is very important because in some companies yet again, it's not visible. Everyone just do based on features functions or pressure from the business people. Stakeholder say I want this picture done but they don't
think through the design. So I think one of the area of these area where it can help is actually to build this team culture. Why is it only lately quite popular? Because I think Michael Knight got wrote the book quite a number of years ago, but somehow this idea seems to pick up quite recently in many different companies. So if you can share, maybe your observation. Why that is so yeah, I've been really curious about that myself. So like why is everybody doing it?
He's ours. Now, I think what it comes down to is so maybe a year or two years before the night guard blog post, Fleek reached in and a couple of co-authors whose name I'm forgetting. Wrote a kind of a challenge to the architecture Community about, we've had like the four plus one View, and we've got viewpoints and IEEE you points. All these things for a long time, it seems like decisions are becoming a thing. We need different ways of
thinking about. The things that kind of got a lot of people thinking about this topic of architecture decisions. They were kind of two branches from that point. One was the architecture Community, they went very deep in View and view models. So there are a lot of people proposing, decisioning viewpoints things like that really powerful techniques, but
also you have to know a lot. You have to have tooling fairly heavy weight to use Nygaard. It was kind of coming from the agile patterns tradition, his approach that he had kind of pitched out there very lightweight text-based. No barrier to entry. You just get started, using it. So I think that was kind of the invitation from my own experiences using it because there are few kind of guide rails to it. Takes a little bit of time to
figure out how exactly it works. Those changing behaviors that we were just chatting about on teams that I've worked on the past. You're looking at six months to two years. Something like that is kind of a journey for, you know, introducing the abr's learning how to use the well, well developing the skills coaching, all that kind of stuff. To kind of develop a team who is able to do these things. I don't know.
Just guessing it seems like a bunch of teams were probably picking up these techniques and the year or two or three after night guards blog post, you figure. It takes a year or two to kind of get used to it, trained up on it. And then from there, it sort of spreads as more and more people getting proficient. So I don't know one thought on it. Yeah, who knows. But anyway now it becomes like a trend in many of the tech startup.
So maybe if a big company who value architecture decisions more and probably, they don't think the traditional No way of documenting. The architecture decisions was probably effective. Anyway, when we have these idiots, I assume if you are a team, which has been around for many years. If we make all the small decisions in the adrc, I guess it could be pretty long as well. It could turn out into hundreds of pages as well.
So maybe any kind of tips here that things that should not be any ideas, how we should manage the ideas better instead of any new developer starting from zero and read. All the Ada has gonna take a long time. Yeah, well I guess a couple of interesting thoughts, what's the most tdrs of ever seen? So I've written a ton of edrs but I think in any particular software system of the most I've ever seen is maybe in the 30 to 40 range.
So that's a solid year and a half of folks, diligently reporting decisions and it's a lot. I think it's the most I've ever seen most of the time it's in the dozen or so that you might see for particular module or something. Someone who owns which I guess when you like, take it all together, can be a lot. Gets that architectural decisions are made every day becoming a Aware of when you're making an architectural decision is probably the most important thing getting started.
I think one thing I've seen recently happening as my teens have been kind of getting more sophisticated or more aware in thinking about design is when we started to look to other techniques to kind of blend with a trrs, my IBM teams were doing architectural hoisting, which is a really great technique. So they would not only write the EDR, but they would and introduced a framework to enforce certain decisions that were made or to enforce certain quality attributes that were
desirable. I think a lot more design rules being implemented these days which is really great. There is a really great framework that my team is talking about just today called Arch unit. Those kind of J unit, testing or architecture, so taking something like that and combining it with a DRS is like a powerful combo, so thinking about modularity, and then blending techniques, blending ways of documenting decisions
seems to be pretty powerful. You mentioned something about knowing when to create the a dies. How do you decide what kind of scope that warrants us to create an ADR? Because sometimes I believe if they don't get some kind of guidelines, they will just probably need to create many awesome. Like, they are not sure when to create right? So maybe any kind of guidelines, when should we create an idea for certain types of decisions, right? That's probably the number one mistake.
I've seen new people who are new to 80 yards. Make is a lot of times you go from no documentation practice, like, nothing and then, oh my gosh, a TRS is amazing. That everything is in a Dr. Like literally anything that's going on on my team, we've got a heuristic, we've got a bunch of questions that we try and get people that answer does this decision deal with one of our most important quality attributes, does this decision bring on new technical debt.
Does this decision materially change the structure in some way? Is this a decision that we can change our minds easily later? If it's something that's like easy to change later, maybe it's not so architectural. That's actually the first coaching Point. What is architecture? What is software? Texture, what does it mean to make an architectural decision? Yeah, the adrcs expose that immediately, you'll see things coming in, like, oh, we should name all the methods with a verb
sighs. That's a good design decision, but it's not quite architectural. Thanks for sharing some of the heuristics. I think some people will find it very useful because sometimes it's not easy to gauge when we should create a Diaz, especially if we begin as you just learned from the books, it looks cool. Other side doing it, let's try. But when you try this, like, okay, when and I think you mentioned, also another Good practice in areas is to actually do a pan only like in Version
Control of pain and not modify. Is there some situation where you need to modify or delete or how do you actually make a retrospective decisions? I guess, how do you do more? Yeah, so the idea behind the append only kind of decision log. It's really about helping you think about and helping you to capture that history. So you don't want to go back and say, like, oh well, we changed our mind. So let's just delete this old one and change it. Make us look really smart, that
kind of a thing. Keep the old one. What you want to do is write a new decision in the update, the old one, to kind of point to the new one, even like take a cross-reference, they can reference back and forth. One of the thing by teens are doing recently, is adding a new section of the bottom of the decision, record for reflection. So in some cases, it may have been six months or a year, since we made a decision we go back and just kind of how did it work
out? Did we actually get the consequences that we thought we were going to get? If you could go back in time and do something differently? Would you have still made the same decision? There are put it down on the Some of the file just out at the end of it is kind of sudden but ditional reflection, people get really uptight, I guess about. It's a pendolino, don't modify na fix the typos. It's okay.
Nobody wants to spelling errors and things but don't like completely rewrite the thing that's kind of the spirit of what we're talking about. Yeah. So how about diagrams architecture, diagrams logical, diagrams data model diagrams and things like that and they also part of any ours. Oh yeah, diagrams are great. 80 yards is all about effective communication. So anything that's gonna help you communicate effectively. Go ahead and put in that EDR. There's no hard and fast rule.
That says, it has to be text only, so my team is a lot of times to keep it very light weight, but used to be in the increased pandemic, as you know, a picture of a white board, somebody would like sketch something up, take a picture of it, put it in the ATR, doesn't have to be anything fancy. Nowadays will see screen caps, a screen capture of like a Miro sketch or mermaid. Then GitHub, is added mermaid support. So people are starting to experiment with that, which is pretty cool.
Kind of having rendered Last diagrams or sequence diagrams in the markdown. So that's pretty cool. But yeah, views are fantastic. That kind of reminds me in a way the decision log itself. It's like a change over time kind of view of the architecture. Another thing that we've had some interesting success with is re mixing so create a new document, maybe it's your security view of the system or your availability view of the
software. You might add a couple of new diagrams, describe a few structures in that and then point to To the most important adrs that are related to that particular quality attribute for you're trying to describe. So, it's almost like a best of if you're interested in this one idea, this is where you go for it instead of only having that historical oldest to newest, kind of view of the world.
Yeah, I think that's pretty useful because sometimes if you just Trace back it takes too long to actually form. What is the current view of the system? Yeah, it's interesting. Maybe not what you need right now. So, maybe since you have done is for many years now, I assume you have found certain patterns and anti patterns that maybe you can share, let's start with patterns. What are some of a good patterns that people should think about when they Implement ideas?
We chatted about a couple of more ready, which I think is great. One of the patterns that I tend to encourage is really anything to get things started. So interesting stuff, a TRS-80 ours, they're lightweight, but sometimes In the Heat of the Moment, it's just a little bit too much work even for something so short as an AVR. But if you Least capture the stub, just like a very brief, what's the decision? And as many notes as you can about the rationale, it's at least a start.
So that's a pretty good pattern. I think that I've seen in a lot of places. Another one, I think we kind of chatted about this briefly as well. I really love to use a DRS as a teaching tool away for kind of coaching. One of my favorite things with that is delegating to people saying like, hey, you write the ADR asking for volunteers, especially, folks, who maybe have never written one before and then letting them do their best, just letting me give it a try.
Bye. And then sitting down and pairing with them afterwards, to kind of talk about asking questions or dig into the consequences, things like that. So there are I think pretty good pattern that I've seen really good tool for eight years. One more referencing 80 yards from the code. So that's probably like the best sign of when the team has kind of made it when you've kind of cross that Chasm, when you see comments in the code that are then referencing a TRS have been written.
So you have this kind of nice cross perks, right? Like, you can see the structure in the code and then people are linking out to other document. And help describe the rationale. That's just huge. I really like that as a practice. And of course, it's all in the Version Control repository. So you know, when they copy it down, you'll be able to find it. It's all there.
Yeah, I like it. When you say that the sign of the teams who made it them, some practicing a Diaz is actually, when they referencing it in many parts of the code as well. So it's not just a silo, one document that is maintained by a few people and the rest of developers, just write the code, right? So I think that's a nice way to put it. How about anti-patterns, so maybe you have I found some empty patterns along the way. Yeah. So some things that maybe don't
go so well. So we chatted a little bit about everything is in a Dr. I've seen that happen on every single team. Probably another one, everything is not an AVR and that's okay for new folks. Especially something that I see is we'll just call it may be simple consequences, you'll have this great decision. You'll have a pretty good context and then you'll see like one consequence. It'll be like, because we
thought it was good. It's like, oh my gosh, that's not a consequence or it'll be, sometimes even sillier than It'll be like the code will be more maintainable or something. Okay, well I mean, at least there's a quality attribute but it's just this one thing. So I think one of the things I really strongly encourage is digging for those consequences. So, go for at least three go for more than three and nearly always when that happens. When you really think about it,
you're like stumped. It's like what could possibly happen, What? Trade-offs could there possibly be. And then all of a sudden, the dam will break ideals will flow, and you'll come up with five or six, more consequences and they're going to be the most Most interesting things that maybe you wouldn't have otherwise thought of this is where maybe you'll consider new.
Technical risks. New engineering risks introduced by the change or particular quality attributes, promoted that maybe weren't a top of mind at that moment. So to few consequences, I think, is a pretty common anti-pattern. So, you mention about all these simple consequences and things like that. Cows, should we, as a team, make decisions together as an ADR? I imagine because there could be many practices like one And delegated.
This make the decisions or is it like every time you want to make a Dia, you do team huddle? Many different practices. How should we make a good decision together? As a team in the form of a Dr. Maybe you can also cover this one. There's a lot of interesting ways I've seen teams to do this. So one of my favorites, I think is a lot of times. I'll see your team together in a whiteboard Jam. Everybody kinda at the Whiteboard, talking about different things.
Everybody's throwing up different ideas. They're asking questions. Taking turns with the marker either physically or Actually we're all remote taking turns telling stories back and forth and walking through our diagrams when that happens sometimes but not always, but when it does, it's really beautiful. Someone will start taking notes to the side about things that folks are talking about. Just right there in the mirror of word.
For example, these are the starts of the adrs in a whiteboard Jam like you're just going through probably three four Alternatives, different ways of structuring things and really walking through hard parts of the architecture it helps to talk that through. Have somebody to explain it to ask questions but then even better is when you have another person to record what you're saying because sometimes you're just not going to remember he's brilliant moments that you're
having. I think that's one way I've seen it come together. Really. Well, I've seen that phenomenon also happened during like mob programming. So when you've got, like, a whole group of people together, working on the same code, at the same time, same kind of phenomenon happens. So, you'll be making design decisions without even realizing it. And that and another teammate will just kind of notice and jot down the notes. You know, kind of create almost a Proto idiot.
Are ready to go. So there's I guess kind of two things. Is that a session last week? I was pretty interesting. We had a big question, so somebody posed a big important question. Believe it involved a certain API technology. I think it was GRCC, we were talking about and whether or not your PC was going to be allowed in a certain part of the
architecture. Whether we would have our services offered year if you see interfaces or not in that part of the architecture with that, it was actually a mob all together. Working on. Just that one decision a shared Google Document People jotting down context and try to get the context laid out talking about like, what are the consequences, bring some real consequences in real time. That was really great.
I think the most important thing that you still have to kind of have somebody go through the final document and kind of phrase, the ADR to share back to the groove, even with like a group effort, you still have to have one person, maybe two in a pair go through and actually like write it up. Yeah. Sometimes It's tricky in the discussion who will capture that may be summarized it because I think it takes some time as well to actually capture down the essence. So my goal has been a pleasure
talking A about these ideas. I learned a lot. I'm sure all the listeners here will also learn from this composition but unfortunately due to time, we have to wrap up pretty soon. But I have one last question. Maybe this is like the sharing your own ideas, right? So what I call three technical leadership is them. It's something that I think it's like an advice for listeners. May be from your journey from the experience or maybe from your expertise. So what will be your three?
Technical leadership wisdom. So I guess folks, we've worked with me for a while. My team is probably find this amusing. I have Catchphrases mantras. Maybe that's a better way to wear things that I tell myself. So one of those is get it working then get it working better. When do I tell myself this? Anytime I'm facing a really difficult problem. Maybe I don't know how to get started. Maybe it's intimidating in some way.
First thing, let's just get it working, get something working at once that something is working then we can get it working better at it. Maybe it's back to my otd roots or something, you get something working to get working better. So there's one second bit of wisdom. Maybe is remember, you're not alone. This is I think Thing that is very thematic throughout design. It is this idea that like, we're all in this together with a great team, you can work together.
Even on really hard problems and design is hard architecture is hard so just remember that you're not alone. I think is really important ask for help, ask questions and people will help and the end result will be awesome. Third, one chatting with my son ahead of time about this question and he encouraged this bit was so I think it's great. The Bill & Ted wisdom of be excellent to each other, I think that's just true. 100%. True design is hard
architectures. You're putting yourself out there, you're asking for feedback a lot on these things. Just be kind to one another. Be excellent to each other help each other. Learn is such a huge thing. I liked the last one so be excellent to each other. Sometimes we develop this one to work in Silo, right? So I'll 0 and then very grumpy about things or very afraid or something but now just be excellent.
Yeah, if we are kind to each other I'm sure we create a better Community, better kind of results together 100. You're not alone? Yeah, we In alone at the end of the day. So Michael for people who love this conversation, if they want to follow up with you ask more questions. Is there a place for them to find you online? Yeah, Twitter will probably be the best place to reach out to me. Probably easiest one. My name is Michael chilling on Twitter. Thanks for that again, Michael.
Appreciate your time today. Hope you have a very good success in promoting, this idea, Sumo people. I know that you are writing a lot of blocks or papers recently, hopefully we can share that to people as well when this episode is released. So, thanks again. Or that. Yeah, excellent. Thank you very much for having me.
This was great. Thank you for listening to this episode and for staying, right until the end if you highly enjoyed it. I would appreciate if you share it with your friends and colleagues who you think would also benefit from listening to this episode. And if you are new to the podcast, make sure to subscribe and leave me your valuable review and feedback. It helps me a lot in order to grow this podcast better.
You can also find the full show notes of this conversation on the episode page at tackling journal. The death website, including the full transcript With interesting quotes and links to the resources mention from the conversation. And lastly, make sure to subscribe to the shows mailing list on package. You know, dot f to get notified for any future episodes. Stay tuned for the next technology, you know, episode. And until then goodbye.