Streamline Document Workflow with Lead Segmentation in IT Architecture Documentation

How to create outlook signature

oh and welcome to software architecture Monday my name is Mark Richards I'm an independent consultant hands-on software architect and also the founder of developer to architect comm in today's lesson number 55 we'll take a look at one of my favorite tools of architecture architecture decision records architecture decision records were coined by Michael Nygaard and he says this about those quote we will keep a collection of Records those are architecture decision records for architectural II significant decisions in other words those decisions we need to make as an architect and he defines these so well those decisions that affect the structure that would be the overall style of architecture whether we're doing micro-services microkernel service based a layered the non-functional characteristics those are the ill ities dependencies in this would be between services or components interfaces including api's or construction techniques which might include processes procedures or even the platform or language that were in and so let me show you how powerful an architecture decision record can be but let's define them first and these are the basic sections that Michael Nygaard has defined within an architecture decision record an architecture decision record is a short text file usually one to two pages long that contains only one decision so in other words each architecture decision that you make would have a corresponding architecture decision record or ADR usually these ADRs are written in some sort of markdown textile or asciidoc kind of format there's no reason you couldn't use plain text as well except the markdown is useful and I'm gonna show you that when actually I show one rendered in a wiki or a browser there's five core sections that Michael Nygaard has identified and I'm gonna show you a couple of others that I've actually added myself when I use these the first is a title it's a short noun phrase that's numbered that describes the actual architecture decision and then the status whether it's proposed and needs to be approved by an architect's Review Board or your boss accepted or superseded I'm going to get into the superseding when I show you some tools that you can use the context really describes the problem and why I am needing to make this architecture decision I also usually include in the context some of the alternative choices as well the decision section is probably the most important this is actually your architecture decision combined with all the justifications and finally consequences in other words when you make an architecture decision there's consequences good or bad associated with those and then it forces us to think about those and document them as well two additional sections that I usually add one is metadata in other words who's the author of this when was it approved who approved this architecture decision if it was modified to change anything when was it modified and by whom and so that hashtag hashtag or equals equals if you're doing asciidoc metadata our notes is a usually another good one a second one that I've been recently adding quite a bit is measurements for compliance or measurements in other words we want to make an architecture decision I'm going to document how I'm actually going to measure this using some sort of automated or manual fitness function let's take a look at an ADR here's our scenario we've got an HTTP client coming into some sort of integration hub for example mule using a restful call now in the backend we've got a customer information system and basically that HTTP client wants some customer information well when the scenario here that back-end customer information system that you see there can only be accessed through JMS and specifically here using ActiveMQ and so this is the scenario where the integration hub does that protocol transformation from rest over to messaging to be able to get that customer information now one of the requirements was to federate the hub in other words instead of just internal calls we're also going to expose some of that customer functionality to external and also b2b through other mule instances here or integration hubs and this is just do - really the availability and throughput now that decision was made and approved we have to make a choice should we used dedicated broker instances in other words have a cluster of ActiveMQ instances per mule cluster or should we have a centralized ActiveMQ cluster when we make this architecture decision it's really important to be able to show the alternatives and justify them let's actually write this out ADR and so this is going to be ADR number 21 and so notice this is the title it's numbered centralized message broker for federated gateway hub here's all my sections right here on the basic one and the status is accepted so this has been approved the context is where I can actually now describe the problem and the alternatives for example the incoming gateway hub is federated into three separate hubs access to the customer information functionality in the application is only through JMS the two options are used centralized broker or to use dedicated broker instances now watch the decision here this is in kind of Michael Nygaard forum it was odd at the start by saying we will do this it was kind of weird at the start but now I use it all the time how many times have you made an architecture decision I think centralized message brokers would be best well that's great but what's your decision you know too many times as architects we make decisions without that affirmative and thank you Michael Nygaard because that we have an affirmative we will use a centralized message broker instance that's my decision but now I need to justify it as well for example we currently have low request volumes in other words what do you mean low 200 requests a second and anticipate this will remain stable for the foreseeable future therefore we don't see a performance bottleneck because that's one of the first things anybody who's going to challenge you would see also we will leverage the outreach notice that we will we will leverage the ActiveMQ failover protocol coupled with clustered broker instances to address the single points of failure look at the consequences though now by doing this the customer information application only requires a single connection you see if we use dedicated instances I would have to have three connections in that application and now because there's only one connection the gateway hubs can be expanded and consolidated without any coding changes in other words if we say hmm you know that wasn't such a good idea there's no changes to the application because it's just a single connection to that ActiveMQ instance and consequently the application doesn't need to be concerned about where the request came from now this is I'm showing a plain text if you use some sort of markdown or asciidoctor textile um this is what you can do with the formatting in a wiki notice here I can also add figures and diagrams to describe the problem I can separate out kind of the alternatives and discuss those and so you notice that it's more kind of formatted mmm documentation really about that architecture decision there's a really cool automated way of managing a VRS and that's through ADR - tools on github and notice here on AV our tools this is a command line interface and so what we have to do is initialize it with where do I want to put these ad r's it's some sort of directory structure now that's usually attached into some sort of github repo and so that I can actually version any modifications I make to these not necessarily changing the decision but if it's proposed I want to change it to accept it and have some notes about that and so watch this here's the command line ADR space new space and then I just simply describe that decision centralized broker for hub and here's what happens with these ADR tools what will happen is it will bring up your favorite editor which ever editor you specify and it will actually create ADR - Oh 21 that's the next one dot MD - for markdown and it will bring that up in your editor if I choose to say hmm we made a mistake really it should be dead I don't change ad r21 you see that was history of why I made those decisions that's important to know and so now what I do here is say ADR new - s4 supersedes 21 dedicated broker and here's what ADR tools will do and this is cool it will create 22 which is the next ADR and it says in that file that it supersedes 21 and then it takes 21 and it says superseded by 22 so that if I go into 21 it will mark that that's actually been superseded so this is no longer a valid architecture decision adrs are so powerful everyone I really encourage you to use these try them out experiment with them add any sort of sections you want but just make them simple and that was really the spirit of these if you want to see that kind of the full block I've provided the link there and Michael my guards blog about these architecture decision records you can get more information about other aspects of software architecture by going to software architecture Monday which is on my website developer - architect Aipom slash lessons where these all these video lessons are located and also upcoming events places where I'm speaking at conferences or trainings public trainings on my website at upcoming events HTML and so this has been left less than 55 architecture decision records again my name is Mark Richards and thank you so much for listening