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.