Architecture Decision Records

When people build out their first version of an application and then maybe move on to a new project, a lot of the history around the decision making process is lost. Why did you pick this architecture over another architecture? Why did you build out a certain part of the application and not the other part of the application? What are the concerns and the things that were rejected? Such information can give you so much context when you're coming into a project around why certain decisions are made and what controls you have there.

Typically, we’ve seen that there's tribal knowledge in an organization. I know to go walk down the hallway and knock on my colleagues door to talk to her about why she made a certain decision on an architecture and understand it a little bit better. However, with the sort of great resignation, if you will, people are shifting jobs and maybe that tribal knowledge is now leaking out of the organization. Hence maintaining an archival process to record decisions can help mitigate that risk of losing some very key information that helps accelerate similar future initiatives. Another use case for this could also be an auditor who may come back to ask why a decision was made and how an encryption or security decision was made and implemented.

The best way to do it is to almost have it live alongside your code. It can just be a plain text document with links to some of the other resources. If it lives alongside your infrastructure-as-code, your TerraForm, your AWS CDK or your AWS CloudFormation, it just records the reasoning behind the decisions that you've made over years and years. That accumulated history is incredibly valuable for educational purposes, for understanding how your application operates. And it also prevents a lot of the redundant work that people will do in future projects.

Adding an archival process is also seamless to a normal development process. You might have a peer review process where you're taking a look at the code. And part of that involves asking where's the decision record for a certain feature or project? Where is the context for it? We can make sure that keeping track of that is committed along with the feature. So it’s not adding anything to the development team other than to help the next person that needs to take on the project and understand how decisions were made and, and what the history of the feature or the platform might be.

It's a great handoff for, for maybe a vendor like Caylent coming on board, or a vendor like Caylent handing off back to a client team, making sure that we've captured all of those decisions so that their team can run with it. So wherever there's a handoff, it feels like it'd be a valuable artifact for the next team to take on that project.

If you’re building applications and would like to leverage the capabilities of the AWS cloud, get in touch with our experts to learn how we can help!