Lead qualification system in IT architecture documentation

How to create outlook signature

hi my name is Michael Keeling I'm here to talk to you today today about architecture decision records in action and the brightest light ever the sitting over there right in your face okay so a question how do you share important design decisions on your team on my team we we rely very heavily on oral history to do this right so you can almost imagine you know everyone please gather around let's talk about how the database will interact with the you know the microservices right oral history is really great and we we get a lot out of it a huge benefit especially when we are early in the design process exploring exploring different ideas right but oral history has some serious limitations okay so very limited reach I'm talking basically one-on-one or in small groups with individuals who are only privy to that one conversation time consuming to share I have to go talk to every person who I want to share this idea with without constant attention right the ideas that you have shared will will basically die out right and and with every retelling it seems like the stories change right so what may start off as a very clear crisp view of the world and the design decisions that we've made over time starts starts to slowly degrade until eventually someday we end up with something that was I don't know it's still the gist of what we had in mind we've lost a few details along the way but you know maybe those are important details maybe not right worst case if we don't write anything down pretty soon we're just going to forget everything right maybe the team moves on maybe people leave whatever the case may be right may the force be with you everyone right so so you know up to date document something we don't see very often right is actually getting things up to date film so a question that we asked in our team what is the kind of with these ideas in mind and wanting to say light what's the least documentation that we could write but still remain effective okay I always like to try and get away with the least amount of stuff so for us our ideal documentation was going to be something that had a very low barrier to entry something we can kind of just sneak in required minimal training right or something that we could do training as we or training on the job something the team would perceive as being useful very very easy to keep up to date and perhaps most importantly of all something that the people who don't want to be documenting stuff the skeptics would actually go along with and want to and want to try and around this time is we're trying to figure out a good way to do this I found this blog post by Michael Nygaard about architecture decision records okay so you can read more about about this on on his web site but the basic gist is an architecture decision record is a very brief text file that captures a single decision and the set of forces that are around that decision okay so it includes the design context I'm sorry the decision itself the context around that decision be the rationale that goes along with it and then any kind of implications of the decision that you've made okay so all right and this is why we do backup things so I was originally going to show this live so that you could actually read the text a little bit but I took a screenshot so knowing that the technical problems inevitably happened so here's an example of an ADR that we have on our our team okay you can see a couple of interesting interesting things here descriptive action-oriented title a number right this is the fifth decision that we've made ADR is going to go incremental e as you go as you're adding more things that those top paragraphs are talking about context so those forces at play what is happening happening in the world that led us to kind of think about this the decision itself you can see well maybe you can't see it says we will organize the agent with a pipe and filter pattern it's a very action-oriented we will do something one sentence the decision right called out very clearly in this particular version we also have rationale that we pulled out we're kind of experimenting with different different ways of capturing this information you see a status this decision was accepted and then finally at the bottom consequences of this decision and what this is saying here is things around a team education new technology that we're going to have to use risks that we would potentially need to accept things like that so positive and negative consequences of the world based on the decision that we've made okay so just to review notice plain direct language very very brief one to two pages max okay we store ours and markdown and we store it with the code where the decision is influencing okay so it goes into the exact same code repository all right we have a template our ad our template includes all the things you just saw and well I've got another example of that and we'll see if you can see it all the things you just saw for capturing the context the consequences and various types of status of whatever that decision is over time the world changes right a decision could be deprecated or superseded by a new decision you don't delete the old record you keep it and add a link to the new thing to the new the new decision all right let's see if we can see these all right here's an example of the template tried to pull it out in kind of a text format that would be something you guys can see notice that we're giving advice kind of how how you should think about this or what you should do right so it's a this is an opportunity for the architect to provide just-in-time education about how to think about a decision and kind of how to fill these things in well oh good we'll show the hidden stuff renders nicely I don't know if that's useful yeah sure so in addition to the template itself just-in-time information about the methodology right what is an architecture decision record why are we doing this and then all of our decisions going again into the Virgen control repository you can see that we have you know 1 2 3 4 on and on and on right ok the advice that we give on our team is this list of things if you're dealing with something having to do with you know influence and influencing a quality attribute or changing the way the development processes work modifying a public interface we would sometimes probably consider that to be architectural maybe I oughta jot down an ADR if you're messin with some of those things this is not a hard and fast rule but it is a good kind of guide for helping people understand what they when they should be documenting these things okay let's talk a little bit about our experience using a TRS so to understand that first thing you going to give you a little bit of context so we're a team of about nine engineers all technical backgrounds with a wide range of experience okay we've got some people with less than a year some people maybe two or three one or two with fifteen twenty years right getting up there very much the median though right we're a relatively young team overall so very few experienced people agile processes scrum and XP tailoring as we go kind of typical stuff we're building Watson okay and what is Watson great question so it's a right now currently a set of cloud-based micro services with many many products built on top of a common platform for machine learning natural language processing things like that within Watson we have many many products of which we are just one and then within kind of our product area our little neighborhood in Watson there's about five or so teams who are working all together to kind of ship that one product our product itself currently probably around 25 or more microservices I haven't actually tried to count it it's just the world is changing so fast and then across Watson just to kind of give this a little bit of context we do have some I'll call it minimal governance coming from you know kind of a VP level around things like security or the platform itself the types of a broad the kind of patterns that we should be using or encourage to use so that's the framework within which we are making our decisions okay so we've been using a DRS since about April of last year and here's just a little bit of data to give you an idea for what that kind of looks like over the past year we produced about 40 48 ers distributed very unevenly across many of our services this was not a mandate for our team it was an encouraged practice okay yeah so what's going on some of our projects you know some of our services would get started turn out to be a bad idea we'll just kill them you know not not pursue it any further several of them have gone to production with varying levels of 80 yards there I think things are a little more interesting if we look at this graft over time okay so yeah so number of 80 ours on the y-axis time on the x-axis you can start to see some really interesting things about how my team went about design because we have that history that we were recording so a couple of things jump out right away you can see that in some cases we preferred to take a more upfront approach well in other cases we prefer to kind of allow things evolve a little bit more nothing good or bad about it just an observation from the data we you can see let's see are we introduced a what we're calling a cross module repository for storing concerns that cut across cutting concerns about midway through the life of this particular batch of work and I'll talk more about what's included in that in a moment you can also see that decisions seem to come in bursts which is I thought very interesting as we were going through the data very kind of bursty things and they seemed to happen every I don't know four to six weeks or so which approximately aligns with how often we are replenishing our backlog and figuring out when next things are coming up so interesting observations and these are things that we can use as a part of our reflection to tune our process and kind of make sure that if make sure we're moving in a right direction right if I didn't see a burst of decisions for a while I might be concerned about that right so are we thinking about things other interesting observations from that graph you can see that though some microservices at that kind of that abstraction that level of abstraction were some rep broad somewhere where we're kind of evolving over time the architecture in general or the decisions that we're making it overall was very evolutionary right there really wasn't a lot of upfront work as a whole that being said for every micro-service eventually they settle and we could see a very clear point when lots of decisions were being made and then suddenly we were done there's no more architecture to do right and that's another nice data point that we can use to understand are we spending too much time too little how is this changing over time I'm not going to say this is necessarily true but it appears that you know more code equals more architectural decisions but that might just be a correlation not a causation so it could have been the people there just like making a tea ours more I don't know not enough data for that let's really go one way or another and I can't say notionally I don't have the data to back this up but it seems like in the cases where people would kind of think through the design decisions there was less rework on those particular services over the long haul again I don't have the data to back that up but it seems that it might be true but it could also be that people who write architecture decisions maybe just think things through more and maybe it has nothing to do with a method at all right it could have just been the people involved so I do wish that we had more data on this and if you guys do end up adopting this technique it would be really awesome if maybe you thought a little bit more about the questions you'd like to answer and maybe we could we could get a little more rigorous here I think there's a lot of potentially interesting areas for us to look at around moving forward over the next several months when our defects coming out you know how are we affecting communication how does the quality of our design decisions change over time things like that I think we've got a nice baseline to start looking into that now okay we did we did do some brief reflection with the team to try and understand you know qualitatively how how atrs were doing and the results were a little bit interesting so everyone on the team agreed that the ADR method was either useful or very useful which is kind of cool that being said they then told me they would only read the a DRS maybe once and they would never look at it again for for many many months okay I don't know it's just an interesting data point I guess one of our data points had to do with onboarding new teammates so though the team as they were moving along might not revisit these decisions often for someone new coming into the project they turned out to be a valuable resource they were able to go in and read the history of all the decisions that were made up to this point what we were thinking why you know why we did what we did and how we got to where we are today which was very very cool biggest complaints there was some problem with like oh is this a detailed design is it's an architectural design you know what should actually be documented and if you don't know your to be looking for these things then the all-important architectural decisions are kind of tucked away and code repositories sprinkled throughout throughout github so there's there was some education that has to happen there the team really liked seeing the history of the project kind of evolving over time and they really appreciated having an opportunity or a simple way to kind of improve their design thinking though the way that they approached structured structured thought alright so that's our experience and kind of based on that experience we have a few tips for you guys to take home if you decide to try this so we recommend storing ADRs in your in your code repository wherever that is in plain text keep it simple make it easy to edit easy to share okay with in our case this led us integrate with our peer review workflow so we're reviewing code but we're also reviewing design at the exact same time using the exact same method and then things were contextually close together which if you know to look for it turned out to be hugely advantageous okay this does introduce one major problem though if every microservice is kind of its own little world of its own kind of small grained architecture we lose something with the with the bigger picture the way we solved this problem was by introducing a cross-cutting concerns repo that repository that held these kind of general architectural decisions that cut across everything so we introduced our own governance within our own team for what our micro services should look like how they should have they should come together as standards and key decisions with those all right all right we do recommend that you delegate ADR creation if you're the architect on your team or at least the architecture enthusiast right depending on how your team has organized you should not be the only person creating these things this is a huge opportunity for you to kind of coach and mentor the people on your team super low risk okay it's very easy to pair with people or to go to the peer review process to kind of teach people how to think about architecture and how to improve their design skills alright I think we mention this briefly but you should peer review these things using the exact same process you do your code it's a great way to kind of spread the knowledge around and over time as the team becomes more competent you can kind of just monitor things instead of having to take a more active role which is a pretty cool something that we did not do a great job with but we recommend thinking about is fostering that documentation habit okay some of the things that we tried is having a kind of a person you know if it's you've got the architect or your architecture champion asking the question after a after a an exploration right so if you got the white board working for a while somebody should just ask hey should we make an ADR for this it goes a long way to kind of getting bootstrapping the the the process here and kind of getting people creating these things and documenting them we tracked a TRS when a decision was made to do it as a task in our backlog it held the team accountable and kind of made sure that if we decided to if we decided to make the the ADR to make the document that it would actually get done all right you saw examples of our templates and definitely recommend that another technique that we had success with was using architecture briefings okay so this is a short presentation 30 minutes are left 30 minutes or less that goes over some piece of the some piece of the system it's all about feedback loops so if you didn't document anything and I may ask you to give a briefing you're going to be very sad right meanwhile if you did document some things you just go read the history it's basically all there and very very easy to kind of recreate and peach others what's going on architecture briefings by the way are another great way to kind of grow the team and get them engaged in engaged in the design process okay we recommend making a decision first and then documenting it maybe that's intuitive but it's not really right so we found that decisions that were proposed before there was any kind of consensus building went through terrible thrashing and most of those pull requests were completely abandoned right you kind of have to go through that oral history and and talk with your teammates and build consensus before you try and shove a decision out to share with the world that being said a DRS seemed to be a good way to kind of document ideas for the future so if there's an idea that you have for improving the architecture or the system in some way you can jot it down as a proposed ADR and kind of communicate this is something that I don't want to do today but I think we ought to think about for the future and I don't want to forget about it right a nice way to just get it off your chest and so you can focus on what's required today as a team you can then review it again in the future when and if it becomes contextually relevant all right a final a final bit here not everything is an ADR okay so I don't know exactly what happened maybe there was like an intense thirst for writing documentation or or you know maybe people were just waiting for to be told what to do or how to do something we introduced a DRS and all of a sudden everything was an ADR right which is not the not the way to do it in response to this we ended up introducing other lightweight text base we'll call them single responsibility records we found that the general idea of keeping things close to the code and plain text seems to be really good okay so we've been experimenting with views maybe there's a simple view template that captures just a single kind of picture that you know short one to two pages the same general principles to capture that view we've done a very good job I think of capturing will be call design guidance or design philosophy kinds of ideas very brief one to do page information that helps you kind of implement the decisions that we're making so that's been very successful and then also you know any kind of governance or or quality attribute kind of viewpoints are the things that we're experimenting with and they seem to be working well how do I not have laptop issues I would actually show you examples of these things so if you're interested in that we can we can look afterwards and I can I can share those alright so quick quick summary so all the tips for ADR is that that we had during our reflection store with your code and plaintext delegate use this as an opportunity to kind of coach and mentor do the peer reviews just like normal work to kind of foster that documentation habit make decisions before documenting and remember that ad ours are just one tool there's lots of other things that you should be kind of thinking about in documenting that don't fit this format alright so I just want to point this out because I think it's really important you guys you know it ATRs are awesome but they are not new ok this idea has been around for a really long time ok documenting architecture decisions cool since at least 1997 probably even earlier than that okay what is it every four three to five years or so somebody writes a new paper with a new template of how to record design decisions for your architecture it's been a standard practice since the very first FCI books okay which is kind of odd because all of a sudden people are talking about this again and this particular method seems to be gaining a lot of popularity and traction and I thought that was really odd and wanted to wanted to think about this a little bit so what seems to be happening I think anyway is that developers are of today are expecting to kind of be involved in the design process more than perhaps the traditional traditional methodologies that we've had in the past and I think this makes a lot of sense right so we're increasing as system increase complexity increases we modularized system greater to kind of in response so that we can deal with that complexity but so ok so what that means is then we need to kind of raise the general level of competence of architectural thinking and design work so that all the individuals can be responsible for all these small little modules that we're breaking up because quite frankly like I can't handle it alone right we've already got on our team close to a dozen microservices and there's no sign of stopping right I can't monitor all of that I need to teach my pee and kind of mentor them and coach them to do it and they want to do it right so we need lightweight mechanisms like this to to to help yeah so there's that seems to be a general shift towards democratizing the design Authority getting away from that central authority and then the role of the architect as I think we've heard a couple times of this conferences is shifting more towards this kind of coaching and mentoring role and I think that these lightweight decision records like this are are one approach for kind of enabling that kind of that kind of leadership all right so to wrap this up here documenting design decisions it seems like a no-brainer cool since 1997 like you should be doing all already why aren't you right but maybe instead of you know saying hey team I need you guys to document design - no thanks no thanks no ATRs they're like yeah I love it we're going to do it you know at least that was the experience on our team and I think that you guys can have the same benefit so getting started super easy okay create a template write one up and then send it to somebody to review BAM you've got an ad are you've already started right you don't need permission to do this you can you can start it on your own grassroots and and you'll be on your way hmm works yeah it's it's spectacular so I hope that you learned something from this talk and you've got a new method add to your silver toolbox and be happy to answer any questions and yeah go go shameless plug please go check out buy my book and yeah happy to answer any questions [Applause] just did you start this at the beginning your project as you end up having to retrospect stuff did you go back and say wow I need to write it I have no idea how that worked can somebody write that up yeah so work work in my office and work on Watson in general is continuous there really isn't a start or an end right and and I use the word project but we don't think in terms of projects we think of terms of like continuous delivery of value in this particular case it was on a team retrospective I introduced this as a piece of personal reflection and thought you know I'm observing these problems maybe this will help it's a good oh no so when we introduced it we started where we were and we just moved forward with it you mentioned that Annie at least initially there were some complaints about documentation being scattered throughout the code sounds like the team kind of got used to that and that's probably how you want it but for maybe non engineers or other teams or later looking back did you encounter or explore any methods of rolling though ETR up into some summary document or you know automatic documentation tools like that yeah so we haven't looked into automated automated documentation one of the things that I'm considering anyway to help try and bring this up let me think here architecture briefings those very small presentations are one way that we started doing that I've been thinking about and kind of talking to the team about potentially introducing architecture haiku as another method for kind of summarizing a bunch of things together and then kind of getting that consistency right there's like there's a worry there right that like all these little decisions spread about all over might harm consistency but under the first the first step was kind of making sure that we had our core governance for truly cross-cutting concerns and then quite frankly like if we get the governance right I don't really care what's in the individual microservices as long as people are thinking right and that's really the main the main focus with this technique architecture document and anyone else really download it or you to nowadays how useful were they to other people yes so that's something that I think we need to look into a little bit the excuse me the one one or two data points that we have on that it seems to be generally useful for new people that are coming in I know the audience oh really is the the team and kind of a maintainer x' so that was one of the things that led to the creation of some of these other lightweight recording methods right so a TRS were good for for us from a technical perspective but we found that our product owner didn't really give a hoot right so we started looking at views and viewpoints and how we can create like lightweight versions of those I hope that kind of answers your question I think it's an open area that we want to investigate but I don't know it seems to be working awesome yeah not really question of a B supplement so we've been doing very similar things on the systems and integration architecture level and some differences of course you cannot store your architectural decision records with the code because in many of one of the projects we had like 13 European countries collaborating we had components being developed by different people we didn't even have access to that code one big difference is that we started documenting the decision as soon as we were aware that it had to be made you