 So I'm curious who here is at their first-ever Drupal con? Whoa, yeah Now anyone here their first time in France? Yeah For me, it's both. It's my first time at a Drupal con EU though I've been to the ones in North America. It's my first time in France and It's been an absolute trip of a week So I hope everyone else who's having those firsts are feeling the same way about their time here So hello, you're here. Hopefully to hear about our architecture decision records and our journey with them at Lullabot And if you don't know me, my name is Andrew Berry and I'm the director of technology at Lullabot you can find me on Drupal doc community and You know as far as like other tech passions I also love home automation home assistants big V2. I'm QTT all these different tools out there And if you wish I was talking about those instead of ADRs, that's totally okay You just got to find me after the session and we can get together and nerd out so I want to frame this conversation with this quote and just read it over let it sit in your mind and Think about coming back to this as we we walk through this journey Do you remember 2021? I mean yes and no, you know, it was an interesting year for a variety of reasons At Lullabot, we had our even though we're a distributed company We all work from home wherever we may be in the States or I'm in Canada or you know in the EU You know, we had our first ever virtual retreat and our CEO had a goal for us as a company He wanted us to Standardize and simplify our processes our ways of working our communication all of these sorts of things But what did that mean? I mean, these are two great words You can put them in bold and they look good on a slide But you can probably twist them into any goal you want So we had to think about how we were going to approach this challenge that he had laid forth for the team So when we talked amongst our Leadership and our engineers and our developers and everyone on sort of the technical side We thought about it in a couple of different ways one was we knew that we wanted to improve knowledge transfer across project teams that we saw that there were rough edges when Different teams sort of mixed who was within them and they didn't all have the same perceptions of the types of work that we should be delivering We definitely knew that we wanted to standardize and simplify the onboarding experience for new developers Whether that was someone who already worked at Lullabot What was joining a team where they hadn't happened to have worked with any of those people before or when we hired at Lullabot and There was this underlying sense that we were spending too much time Solving the same problems over and over again that were functionally equivalent But just happened to be different had either, you know a code or a user interface level or something like that So as we thought about these challenges, we thought okay Well, let's observe and think about how our projects and how our teams are currently working today So, you know in 2021 we had a couple of those such as Team members often were moving as a group between projects So if you're not familiar with Lullabot, we're a digital Drupal agency been around since final 2006 or something like that and the way our teams work is that You know you join a project you work on the project You hopefully finish the project and then the team becomes free and we can sell them for a new project So it wasn't always happening this way But often they ended up moving as a group from one project to the next with minimal change between those teams Part of this is also because we fully dedicate our developers to a single project at a time Which meant that they weren't being exposed to different teams on a on a daily basis unless they made an effort to expose themselves To the work that other teams were doing and so what this meant was that we had lots of great best practices but they were team-based not company or project-based and so They would sort of shift with those teams as they move between different projects But if there have been three projects done by team a and three projects done by team B They might actually have fairly different technical implementations for similar functionality Now what was really interesting about this is when we started to evaluate the solutions these teams are coming up with It was actually a real challenge because they all had good solutions You couldn't look at them and say like oh, you're really hacking Drupal in some horrifying way We should not do that in any of these projects. They were just they were different not even for the sake of being different They were just really trying to optimize their solutions very specifically to the clients that we were working with and This really does mirror the Drupal community the open-source community where you might say that different open-source CMS is our Multiple good solutions to the same problem space. You can't necessarily go Hugely wrong by choosing any one of these best of breed Software platforms that are out there like I don't know from a developer perspective if you're choosing Symphony or Lara vol you might have preferences for each one, but they're both going to let you get the job done and get the job done well So was this a problem of communication could we solve this by Thinking about how we talked and shared information with one another Well, think about all of the places where we communicate so We are all here. We all have to go to Drupal.org to buy our tickets We have some sense of how that works, but you know, there's issues And all of the work in the Drupal core space contrib modules that our teams were working with You know, we used to use IRC for those of you who've been around forever There was a system called Freenow. There's kind of like slack for super nerds and you know, I mean, I loved it It was great but you know, we had all these decisions and discussions taking place in chat on that system where even out of the box it didn't have any way to Store the history of what those decisions were unless someone made an effort to put them somewhere else Imagine a lot of you are familiar with Jira and you know, Jira is a project that has been around for a product That's been around for what 20 years now And so, you know, you might have decisions made for your internal work or for your client projects there Of course, we're all familiar with github. You have decisions and communication happening there And then Freenote actually died if you weren't around for that like it the ownership completely fell apart They there was a huge mess and like that entire system of communication is gone And I couldn't tell you how to easily find a decision that was made That was really important to Drupal core if all it was talked about was in IRC Even though I was like living and breathing that for I don't know 10 years And then, you know, of course, we've got confluence for wikis. We've got slack today So there's so many different places that we make decisions So communication like if anything our problem was that we had too much communication, right? Like we had all these different places we could talk to each other, but no place to say Here's where the decision was so if Improving our team communication couldn't let us standardize and simplify Maybe we could do this with documentation. So let's think though about some of the challenges of documentation in technical teams This is a real request from a client we were wrapping up a project with them and They were gonna have this gap where our team was rolling off because we were done our time on it But they didn't have any engineers or developers in house And they wouldn't for several months because of their hiring processes And so their project managers were then going to be responsible for managing the site And they were obviously nervous about like what to do if the site stops working now You know this really isn't a documentation problem The problem was they didn't have the staff to properly support it Or they didn't have the budget to hire any sort of agency to do, you know long-term support for them But just think about all the things that can go wrong during an outage You know it could be your hosting provider is down It could be you try to do a droop droop will upgrade and something broke it could just be that the internet is having a bad day and Packets are going off to you know, nowhere It could be that your site is just getting a new bug could be a security issue a DDoS attack Any of these things and what they wanted was documentation that was understandable and that was There's those two non technical project managers could feel confident They understood what all those steps were so that they could direct future in-house developers But when it came down to it This really was a bad documentation request because it didn't have a clear audience The audience was essentially anyone who might be freaking out because our website is down And when you have such a large problem space, how do you turn those into actionable next steps of? What to do you have to kind of be a little bit of an expert to just narrow down where the problems could be and those steps are not Necessarily repeatable or testable. What are you gonna do like DDoS your own site so you can practice the steps for bringing it back? I mean some might but only if you have those engineers and developers which they didn't have and you know There's also they weren't asking for the documentation in a tool fit for the purpose because a lot of those sorts of action items that you might try and Write down are tied to the current state of your code if you upgrade Drupal if you change a contributed module If you change a content type all of those things could change what your steps are so You know in the end. That's where we landed with this And you know we knew that going back to standardize and simplify We were getting this feeling that we needed to do documentation But we weren't sure how we could avoid these pitfalls and when we look back there actually were prior documentation efforts at Lullabot, but they all kind of sputtered out after two or three months and It was at least my hypothesis. The reason they did is because we didn't clearly define audience or scope for those documentation So like I said, this was early 2021 and I'm from Canada and in Ontario and everything was locked down that January and it was really sad because we had viewed A full snow we had heaps and heaps of snow and all the ski hills were closed so I was stuck at home and You know needing something to do. I started to set up home assistant, which is a home automation tool It's a lot of fun. Well, you know, we can talk about that later But you know, I had a question about how I could set it up and get it running and so I'm reading their documentation which is pretty good and I found this in the home assistant documentation and I wanted to run it on Ubuntu because that's what my server was already running and it very clearly said not not No, there's two supported operating systems use one of these two and I was like, but that means kind You know Debbie and Ubuntu. They're very similar. Like maybe I can just make it work the way they want it to and What was really interesting was they had this make it compliant with ADR 0014 and There was no more information just a link, but I had to click that like, you know, what was this some upstream standard or something? And that took me to a different github repository that started to blow my mind because here we have a record of Exactly what they consider to be in a supported installation method for this open source software and We can see that there's the date the decision was made We can see a status which just looking at this implies there must be other kinds of statuses Otherwise, why would you have everything this thing except accepted? They had a link to a previous document that explained why they had to make the decision and then this is just you know, I've zoomed in a bit here But this is just the very beginning of it because if you scroll down It's got all the information about from a technical level what you need to do to have this This this installation method supported so I'm really curious because I'm also thinking about standardized and simplified standardized and simplified What are we gonna do here? So, you know, I had to walk up a directory. Let's see what else is in here and We can see there's more of them Than this but we've got some, you know, very clear like hey, what's the minimum Python version? Web scraping is a fun one for all the you know developers in the audience where they basically ban code that parses HTML Because they're like we had so much support problem so many support problems with it We're just we're not doing this anymore, but what's this first one that says record architecture decisions? Well, again, this one is actually really short. I've got the entire thing listed here And it's got a link to we will use architecture decision records as described by Michael Nagard Okay, let's walk this chain one more time and we get to a blog post and Look at the date on this now I was doing this in 2021 and this was November 2011 when it was published and This was really fascinating because they were referencing something outside of open source They were referencing something outside of home automation and it was nearly a decade old How many blog posts have been written ten years ago that are still valuable, right? That are worth linking to that haven't aged to a point where it's just not worth having anymore and that's where This line came from so, you know when we think about valuable types of documentation Even though it wasn't an architecture decision record that blog post was Really valuable documentation. It was standing the test of time. So what is an architecture decision record exactly? It's those three headings really Context decision consequences you want to document why you need to make the decision How many times have you had a two hour long group call with team members where you're talking about some issue? And you're just thinking in the back of your mind Do we even actually need to do this like can we just sidestep this entire problem? Do we need to make a decision now well the context forces you to Describe to your reader why the decision was worth making in the first place and then the decision What you're actually deciding to do how to implement it any references those sorts of things and then finally and this is I think are really the sort of genius of Architecture decision records is the consequences and the consequences Can be and should be both the good outcomes and possibly the bad outcomes What will be helped by making this decision and who will possibly have a harder time because you've made this decision And it also allows you to look back at those older decisions and see how good you were at predicting the future, right? But there's several things that an architecture decision record is not So an ADR is not a choose your own adventure You don't want to be reading through an ADR and left with questions about how to implement the decision What the decision means you don't want to have to make any choices in an ADR? It should be very straightforward. Here's the context. Here's the thing to do You could have debate about An ADR itself as to whether or not it applies to a given situation But not necessarily once you've determined that it applies what the action items should be An ADR should also have a reasonably long life We use the the guideline of months to years at Lullabot because if you are going through the effort of Thinking about a decision writing an ADR and then you know two months later It's no longer worth it then you've just burned a bunch of time and you're not getting the value of that It's kind of like automated testing right like you spend weeks or months creating a bunch of automated tests And then you throw them all out because you're changing your website so much like the only way you get the real value from them Is when you're running those tests for months or years at a time You know it's also one of those things where if you in expect an ADR to change then is it really a decision, right? Like you're kind of just masquerading a debate as a decision And you really are then just thinking about the state of your project not the the direction you want to go in But likewise technology changes and so can ADRs ADRs can be updated in place if you don't change the substance of the decision So for example in home assistant when they bump their Python version that is the minimum that's required they don't go through a whole process of Deprecating the old ADR filing a new one getting it reviewed They just change the version number in that ADR because really that's just going to keep going up over time You don't want to end up with like a hundred old ADRs just saying hey, we're on Python 2.8 And now we're on 3.1 or whatever it is No, we use this at Lullabot for decisions where maybe a Module changed a little bit between say Drupal 9 and Drupal 10 and we might just update the guidance like use this Drush command instead of that Drush command But there are times when an ADR is going to be past its prime You can imagine that if you had a bunch of ADRs and you could have because this whole System existed just because you know I didn't know about it or we didn't know about it in the Drupal community there was probably somebody out there who has a library of ADRs all about a Drupal 7 website and You can imagine most of those don't apply when they get that upgraded to modern Drupal, right? And so that's fine. You can mark them as deprecated. You still leave them accessible But you change that status so that if someone needs to understand the old historical Decisions and context they can but if they don't they just know to skip over it So, you know the other part about ADRs is that they don't replace all your documentation They should only document decisions. They don't replace the read me in your github repository They don't replace your setup instructions for how to get the site up and running They don't replace test plans or QA plans or anything like that. They don't necessarily teach you anything new They don't say how to run automated tests on this project or how to pull down the database so that you have a new version of that You know, it's really about the decisions and then all the work whether that's tickets or pull requests or however You're managing that would flow out from that So this made me wonder like our ADRs the battery powered can opener that's gonna let us Unstick all of our previous documentation efforts. Is this something that we could bring into Lullabot to Really solve this problem of standardized and simplified So we Wanted to get started kind of on easy mode We knew that if we went straight to the most contentious the most difficult decisions the ones that our team was not Clearly an alignment on we would stall out and not get anywhere so one of my colleagues Darren Peterson came up with this idea of invisible standards and We call these or we consider these standards that everyone is doing anyways Without question, but we haven't written down at all We don't talk about we just expect and when we go back to our goals around say hiring new developers This is like the worst kind of standard you can have Because they spend their first week working on a project and they do some work And maybe they have some other ideas from previous jobs previous projects They've been on and they might clash and they came, you know, you don't want to be in a situation Where like your first three pull requests are You know have lots of needs changes and reviews and so on you want those people to be successful So, you know, we wanted to figure out what our invisible standards were and get into the habit of writing ADRs around them because that should theoretically be easy so here is our first ADR environment indicator and This one is all about the environment indicator module anyone here who's here familiar with environment indicator See, there's almost a standard in this room for using it So if you're not familiar with it What it does is it tells you which copy of a site you are working on up in the admin toolbar at the top of the screen So you can imagine you've got your production website Where you might be if you're if you're someone who works on content logged in making changes Whatever you might be doing there. You might also have a dev or a qa server running a copy of your site You might have a pull request environment such as through tugboat or Any solution like that where every single change is getting its own dedicated environment and you don't want to get confused like You know, I've definitely done things like there's a bug report And so I delete or start changing content with you know cat pictures or whatever and that was on production That would not be a good day So, you know, this was something we were already doing on all our projects and we started to document the decision And one of the things we want to do getting back to that like don't have any questions Is it shouldn't be install environment indicator and then ask your your technical lead or your project manager? How should we configure it? It should tell you how to do that already and so we knew the real Configuration that was important was what the color schemes were which in this module you actually configure in settings dot PHP And here's what we ended up with but we discovered something Interesting and kind of horrifying as we were talking to our teams about what they had some of our teams had red as live like we've got here and Gray as your local environment Some of our teams had them reversed where gray was live and red was local like and can you imagine you're changing Projects and you think you're on your local and you screw something up like that's really a challenge We also discovered that Our colors actually failed accessibility contrast checks based off of the size of the text that environment indicator was using for the words That would say whether you were live or dev or whatever environment that you had And so we were able to do the work figure out what made the most sense Standardize on that we even contributed some upstream Documentation changes where we saw that there were also other examples environment indicator failing accessibility checks and then you know in the ADR You know we have this copy and paste snippet. That's just like throw this into your settings file And you know you're following it along with all of those different environments and It really turned this from a decision from a debate from a discussion into something You don't have to think about if you're kicking off a brand new Drupal site or you've inherited a project that you're doing a rebuild on you've all of a sudden got like your first week or first two weeks of tickets sorted out and You can just knock through them one after the other depending on how many of these ADRs actually apply to your given project So where are we at right now? This is the homepage of architecture dot lullabot.com you can go to that It's a completely public website all of the content on it is licensed under the creative creative commons for dotto license you can even download the markdown source files and use them in your own projects and The majority of our engineering team has taken part in at least 180 are which is I think something that's really neat to see Let's take a look at another example of an ADR Probably want to give me hands it who's familiar with the simple add more module Yeah, but you work at lullabot or work with us. It's not the quite the same but this is a module one of my co-workers created which helps improve the user interface of cardinality fields anything that has like a set number of values and It's pretty great because there's literally no configuration. You just download and install it So in the ADR we don't have to say how to configure it. It's just turn it on and you're good to go One of the reasons I wanted to highlight this ADR is that we added an alternatives considered section, right? What did we think about and decide not to do and in this case? There's actually a Drupal core issue that has sort of the same goals same type of implementation But it's using client side JS instead of doing its server side. Oh, no, sorry. I've got that backwards The yes the solution that is in the module uses client side JS and I think core maybe doesn't but anyways The point doesn't really matter What's important about this is we've got a breadcrumb as to what would make this ADR not Valid in the future that issue that we're linking to gets merged Then we can deprecate this once we know our sites are updated to the latest version of Drupal and in this case We don't have any bad consequences and you know, luckily I mean we've had this ADR for a while now and there haven't been any but it's also because it's pretty simple So it turns out that the answer to that question of this a documentation problem or a communication problem Like all good engineering problems. The answer was both So, you know in practice most of our ADRs start in slack Which I think most of us are familiar with so, you know in slack We're having lots of sentences timely responses I have a problem right now and would really like an answer in the next hour if possible And slack is also one of those mediums where it's kind of okay to lose the conversation in the back scroll You know if you work at a larger organization and you take two weeks off You're not going to read every single slack message that was posted. That's just asking for a bad way to get back But when these conversations happen, they usually don't start out by saying. Oh, I've got an idea for an ADR They usually start out with I have a problem can someone help me with it or I'm working on this task But once they grow once people start to you know, press shift enter and use paragraphs and it becomes a real discussion We now use Discourse which is an open source form software. You can self-host it But we are we are happily paying for the hosted version because it's exactly the same as the Self-hosted code and we like to support companies that do open source that way and they have a plug-in for slack That lets you take a thread or a range of messages and push them to a discussion in Your discourse instance, which is great because we can then when we see those discussions when they get to that point Where it's like oh if someone's on vacation and they should probably read this and catch up It makes it a lot easier for them to do by going to that that site so They grow and we push that over and then as we you know have those discussions We use github issues specifically for you know, there's a task to do like we have decided to write the ADR someone needs to do it or There is a you know a change to an existing ADR that we we need to make so Let's take a look at a couple of examples of you know some of those discussions. So like here Andy at Lullabot. He asked You didn't even ask a question. He's just like hey storybook has default telemetry on What do we think about that and we had a conversation about what that meant? But then we realized again like this is bigger than just storybook right like I think yarn has default on telemetry I know Gatsby does you know a lot of sort of the more JS tools are starting to do that and Regardless of your position as to whether or not that's an okay thing to do It's still a discussion to have in this case We did realize that we couldn't necessarily have an ADR that described if we Would universally opt in or out of telemetry because what if it's an open source project where they are Publishing all of their telemetry for the benefit of the community. What about Drupal org data, right? You know modules installed all of that and so because it was something that really was more of a case-by-case basis You know we didn't make a decision and that's fine You know the cheapest decisions to make are the ones that you decide hey We can put this discussion to bed for a while and come back and re-evaluate it But because it's in discuss if two years from now You know next JS does something awful with telemetry and people are really wondering what our policy is They can at least search in discuss and hopefully find this thread Here's another one where Some of our projects were using npm for a JavaScript package management somewhere using yarn and I was doing an investigation on it for a client And I was like hey should we use both should we not use them like you know is a project specific and again We didn't really come up with a final decision on this We determined there was too many variables in place to be able to Standardize on one tool or the other But Here is an ADR that actually was accepted an example of an issue So we you know we always try to link back and forth If you are familiar with Drupal's Multilingual UI One of the things that it does is that by default it shows a drop-down with the language searcher of And it's sorry. It's not the language switcher for like what site Language I'm not using it's for what this piece of content is and we kept discovering that Our clients our editors would go to translate a page But they wouldn't go to the list of languages and click the link that says add a translation for French or whatever language They would just edit the English version Delete all the content and then put in their translated copy and change that drop-down from English to French or whatever language They were using which meant they were losing that page and that You know caused a lot of pain and so you know, this is something we realized That whenever we're doing a translated website, we really need to fix this and so you know, we had this Discussion we described what need to be done and you can find the ADR on architecture dot lullabot.com right now So to Accept a lullabot ADR we have a couple of guidelines for that one is we don't document what is already a default in Upstream software or communities, you know, if it's Drupal coding standards, for example There's no point for us to say hey, we use those because everyone should be using those we don't want to duplicate Documentation that is well written that exists elsewhere We also Expect our decisions to be able to be written as a single title and our guideline for that is if someone is an expert in The domain that the ADR is written in they should be able to read just the title And nothing else and be able to implement that decision. So for example, we have a bunch of ADRs around composer There's an ADR that says When you use the composer patches plug-in always include the patches References inlining composer.json never use a separate file and I don't have the title right there But you know, if you understand composer if you've used composer patches even again if you don't necessarily Agree with that as a new lullabot employee or team member You can read that one line and go on to the ADRs that you maybe don't understand it immediately We also expect any ADRs that we accept to be in effect for at least one year And we actually have another guideline that once we accept an ADR We are going to stick with it for at least three months We haven't yet run into a situation where we've accepted an ADR and like two weeks later had real You know choice regret about what you know what we've done But our thinking is that if we've gone through all this effort if the team has agreed that an ADR is the way to go It could just be a problem on the project, right? It could be something very specific that causes it to not work in that one case And we need to give an ADR at least you know a second or a third time to realize that we've made a mistake But maybe we'll never need to do that. I mean, I'm sure it'll happen at some point But we'll see and then likewise an ADR needs to be a baseline for all projects that we start or inherit And what I mean by that is we are very collaborative with our clients We do work in agreement with them, you know at a sprint level on a ticket level however We're running the project, but these are decisions that we will implement without asking the client, right? Like they get environment indicator. It just shows up. We don't ask them Hey, is that worth putting into a sprint? It means these are decisions that are so key to our work that if we have to do it As unbuild time we will do it because it saves us so much in terms of team consistency over the long run A Lullabot ADR is also a list of deciders We include the names of every team member who participated in Slack discussions discuss discussions phone calls anything like that So that if five years from now someone thinks that there's some missing context or they have questions about an ADR There's a hopefully at least someone who has that background that they can reach out to and honestly You want to be clear that this is not, you know me Andrew Barry director of technology making decisions This is really, you know about laying out the framework for how we make the decisions But then empowering the team to do that together Our ADRs are written in markdown and stored in git and they're rendered with a Gatsby theme plug-in that one of my Colleagues put together and they're released under creative commons license, you know these Four items may be different for you for your project your team your company You may decide that your flavor of an ADR is different and that's fine You know a lot of these like I do think markdown and git is a good way to go But you know, I don't know if we we probably and we might use next j s if we were starting a new Implementation of the front end or you know me you're like, oh, let's do a Drupal site like that's fine You know, you want to do something that works not something that Ends up being a project on itself So I gave a version of this presentation in 2021 and I gay had these next steps for you know goals for the the year and You know at the time we hadn't implemented discourse. So we did We wanted to make the ADRs public and we did and we wanted to move on to Documenting decisions for higher cost problems. We did I think probably one of the Most in-depth decisions we made was around local environments at Lullabot We very much believe in people using the tools that they feel make them empowered and the most efficient and that meant for Until I guess 2021 2022. We didn't have a standard local development environment It was do what works best on your operating system your way of working So we had a working group and that working group concluded that we should standardize on D dev for local environments And we documented that as an ADR And using ADRs on client projects, which we have where you have to make a project specific decision is this site using layout builder or layout paragraphs or some other way to do landing pages is this site How is the site handling multilingual or menu management or any of those sorts of things? but again, those should be things that are specific just as we don't want to duplicate the Open source communities documentation best practices and Lullabot ADRs. We don't want to duplicate Lullabot ADRs in client projects So moving ahead to 2023. I think these numbers are probably stale now But we have 30 at least 35 accepted ADRs We have two or maybe three deprecated ADRs many many participants We have ADRs in place on client projects We reference our public ADRs in sales proposals and upstream issues as a way to say hey this bug fix is important our team is standardized on your software in this way and You know, this is how it affects us or when a sales proposal asks for technical details about how we implement a Drupal site Often we can reference those ADRs ADRs have been conceived and moved fully through the process without manager involvement at Lullabot You get a sabbatical at 10 years with basically an extra month of vacation I took mine this summer and it was wonderful and in that time an entire ADR happened I came back to work and like the discussion the Genesis all the way through to being approved and merged was done And I was really excited to see the team take the lead that way And you know, there's been some considerations on using ADRs in the broader Drupal community There was at a great blog post about decision record keeping in the schema.org blueprints module and You know, it was neat to see sort of other people taking this idea and run with it So, you know, we've got a couple of things we need to work on we need to deal with our backlog We've got like 30 open issues on GitHub right now Some of them are probably 18 months old and you know that I need to like do some gardening there We had a slowdown after the initial burst of ADRs We're getting a new one in probably every two to three months and we don't have any as many public ADRs on front-end decisions And that could be because it's harder to standardize the front-end because our the designs are, you know Be spoke and unique and there's a lot that you can't necessarily standardize on or maybe it reflects the bias in the way We are managing and directing our teams that's pushing them more towards, you know Back-end focus instead of front-end focus and that's something to work on So perhaps you see this this could be a way to get involved in a Drupal project even if you're not a coder, right? You know, I think some of these have already happened But you know, maybe there's a community or contrib project You're working on where you're making decisions right here right now and that are of architectural significance Nothing stops you from throwing a markdown file in a doc slash ADR folder in your Drupal project containing these But you may be wondering how to get started So really just start writing, you know, the act of writing an ADR often by the time you get to the end of it You're like, oh, this is a really bad idea. Let's go back and rethink things But the act of writing it can really help crystallize your decision-making Probably just use markdown and git because it's what we all use for our day-to-day work Your developers will be much happier using that and we're participating in the decision process than using a tool like Confluence and it's okay to take your time like really, you know, some of our ADRs They take two or three months to get to that end state and that's okay because we want to make sure we're making the right decision Well, not the wrong decision fast So I'd like to thank everyone for attending. I'll leave you with this last ADR But otherwise, I think we can open it up for questions. So thank you I don't know if you can hear me yet. So there's one question as a decision is only as good As the knowledge and facts at the time, how do you decide when an ADR is ready for review and see if it's still valid? So you when you're thinking about ADRs that have already been published Usually the way that happens is because we're constantly Implementing these ADRs on our projects because it's a baseline There's a natural review process happening there where you know, especially as it was happening with our Drupal 9 to Drupal 10 upgrades For example, there was some changes in our Drupal deployment steps. I think there might have been one or two changes in the composer ADRs so, you know, the best way to review your ADRs is to use them to keep them front of mind if You know, you write them and then no one is thinking about them using them on your projects Then they are going to go stale It's gonna feel like a chore when you have to review them and it's gonna rapidly lead to your repository going to an archive state What was the biggest challenge to getting this process implemented? Yeah, um, I'll I'll say two challenges well, no, so like the biggest challenge from the process side was really getting the team used to the idea that we make decisions together and sort of Coming to terms with losing a little bit of autonomy that way, right? like that's just something that we had baked into our culture and You know, I don't think this would have worked if we had had a small group of people making all of the decisions We needed to give people a voice But then make it so that they felt like they were involved and listened to and considered so that even if a Decision didn't go the way that they would have preferred they feel like they are supporting the rest of their team in those decisions Right like it may mean, you know in those consequences a decision may make my life a little bit harder But if it makes things easier for another 20 engineers on the team Then that is a good decision to make for the for the health of your your team in your project I'll also say, you know one thing that's a little bit different that happened at all about during this period of time as we became an ESOP which is a form of employee ownership and I think that also really was pushing people towards this mindset of What we are doing is both good for the company as a whole and good for me because if we can make all our projects better That will pay off for every employee in the long run And how do you you know if there's already an existing ADR for current problems? If there are hundreds of ADR hundreds of ADRs, there's a search box at the top of the ADR website Highly recommend using it and also because it's in git like you know, if you're a super nerd like I am You can just run git grep something and you'll probably find it And how do you measure success velocity adoption number of participants? Yeah, I mean I think the the biggest risk that I saw is that we would make decisions And then those decisions would grind our projects to a halt right? what if we had a bunch of onboarding ADRs and all of a sudden it was adding six weeks of development to every project that we weren't really considering so I would say our success is measured in the fact that that hasn't happened that it's improved our you know per project velocity that way and Yeah, you know for me It's like the success is not the fact that we created an initial library of ADRs But it's that the team is you know working on them that many in the team are proposing them I mean even people from our strategy and design teams are involved and sometimes have proposed ADRs for things around editorial experience and so to me at least I think that's a really good marker of you know success and collaboration Thanks, and what other documentation are you creating and how do these other types of documentation work with ADRs? Yeah, so I mean from a technical level most of our documentation ends up being markdown files and github And so they're easy to link to easy to reference one way or another We will reference the ADRs and client tickets, you know, we are doing this because of this decision You know, I would say that some of our projects do have internal wikis confluence SharePoint, you know, whatever they're using but one of our reasons for making the bulk of our ADRs public is Because then we can reference them from internal private tools, right? We didn't want to leave our clients in the dark about why we made a decision if they were taking maintenance or a development of their site in-house Cool makes sense And I mean two more questions, but they're very similar Is there an ultimate decision maker if devs can't agree on a single decision? And if there's no consensus, do you put step put your foot down essentially? Yeah, yeah, absolutely And so we do have a couple of team members who have volunteered to be maintainers of ADRs And we have some of our back-end expertise some of our front-end expertise you know they Their their role and honestly my role is less around putting our foot down and more about unblocking decisions, right? So, you know, if you see a lot of back-and-forth in Dis in our disgust form, for example, we will say hey, we're gonna put our foot down Not in a we're gonna stop this conversation We need to actually like have a synchronous call do a zoom chat or do zoom call or something like that I will say that because we have this heuristic that it needs to apply to all of our projects We do do a lot of checking with our support team to make sure that we're not making decisions that they feel like they would have to undo So they are equal and valid participants, and I think that really helps You know ensure that the decisions we make are valid for a project over the whole life cycle Thank you Okay, I don't even know why I went to write this question So this seem to be mostly the examples I mentioned are like linear things but that happen in every project Examples, but I can think more of things where you find a problem that you're crossing every second project at some point and then Based on some condition you need to make some choice, and then you still want to Write it down. Maybe right. It's not so simple So in those cases we try to include the condition in the title, right? so, you know for example if you're doing a project that Is next j s you're not using composer those decisions don't apply We have tags on all of our ADRs so you can filter them if you want to say I want to know everything related to JavaScript or DevOps or Drupal You can filter that list down fairly easily to get what you're looking at But if it's something that's every other project if those projects have the same technical base Then that means it's not ready for an ADR right that means we would probably stop at the discussion level and have They're the heuristics for how different teams made different decisions another question Sometimes you have this problem solution thing and you when you search you only know the problem But you don't know the solution and the ADR title would be the solution and not the problem So that I was thinking that should be some separate thing where you record the quest the problem in one place and the solution linked so the the ADR title is the summary of the decision not necessarily the problem or The solution if that makes sense. So like if the problem is Drupal.org is down for maintenance and you can't run builds because all of your patches are referencing Get dot Drupal.org like that's your problem, right? But the decision is You know always download the patch put it in your local repository and that just happens to be the solution So because we have search right if you search for patches or Drupal.org or Composer you're gonna find that because we are indexing more than just the title. We're indexing the whole thing I think that's everything Yeah, okay. Well, thanks everyone feel free to come on up and it's glad to see everyone here