Documentation is fundamental in software development, especially for capturing software architectures and the rationale behind key decisions. 

Recording both what was decided and why it was decided, fosters a product-focused mindset that supports system design and provides a framework to validate implemented choices. 

At Indexnine, a product engineering services company, we have effectively leveraged Architectural Decision Records (ADRs) to enhance the development process for our enterprise clients, which has been instrumental in helping their products go live smoothly, without issues. 

Here, we’ll highlight our refined approach for documenting these essential system design and architecture best practices, enabling a structured and reliable process for “go-to-market” of your software products.

What is an ADR?

An Architectural Decision Record (ADR) is a record to capture any requirement or a decision that qualifies as an ASR (Architecturally Significant Requirement). 

But then, what is an ASR ( Architecturally Significant Requirement ) ?

Answer : An ASR is any requirement that has at least 1 of the below points : 

1. 1. 1. 1. 1. Technical Risk – ( Impact on components in a tech stack used by the product incl. Non-functional Requirements[NFR] )
            2. Business Impact – ( Change of functionality aka Functional Requirement [FR])
            3. Optimisation of Cost – ( Cost / Budgeting impact )
            4. Security Risk – ( Vulnerabilities, Privacy, etc. )
            5. Stakeholder Involvement – (E.g. Client’s involvement or other required from stakeholders )

Below are important links for further reading about ADR :

1. 1. Github ADR
   2. AWS – ADR Process
   3. Creating ADRs
   4. ADRs

Why should I use an ADR ? Benefits?

1. 1. Organized Decisions – ADRs are maintained hand in hand with code changes.
   2. Developer-friendly – ADRs are stored in git making it friendly for the development team.
   3. Team-aligned Workflow – ADRs save separate change management process / tool. 
   4. Evidence-based Process – ADRs contain the context, justification and deliverables which serves as evidence in the decision making process.
   5. Vetted Solution – ADRs help in linking the decisions to action items which validates the feasibility using a proof-of-concept.
   6. Learning Enablement – ADR process helps in knowledge sharing between all team members
   7. Product Mindset – ADRs help developers cultivate the “product mindset” by focusing on the “why” of the decision taken instead of the “how” of the decision taken.

How to decide if a decision should go in an ADR or not ?

The BOSS Criteria

“The BOSS Criteria“ serves as a decision guide for developers to decide when a decision goes in an ADR and when it should not go.

We evaluated every decision against these criteria to understand why a decision should be recorded as an ADR. 

Any decision/requirement that has at least 1 of the below 5 reasons qualifies as an ADR :

How should I implement an ADR process ? Implementation ?

As part of Architect’s Forum at Indexnine, we implemented the ADR process for our enterprise clients in 3 key phases as below :

Phase 1 – ADR Proposal : Use tools to meet & propose decisions in an ADR.

Phase 2 – ADR Approval : Use tools to meet, review & accept/reject ADRs from the previous stage.

Phase 3 – ADR Implementation : Use tools to meet, review implementation/deployment & if needed supersede ADRs from the previous stage.

Finally, should I use it or not?

The Good

In summary, if you want to achieve any of the below points then we strongly recommend to use it :

• • • Makes you think from the end-user perspective ( Product Mindset )
    • Helps you to identify the process of taking a decision for architectural changes.
    • Makes you focus on the “Why” of the decision instead of only the “How” of the decision. 
    • Forces you to think about options that you were not considering.

The Challenges

In our experience, we found the below 2 challenges for using ADRs :

1. Active Maintenance
   • The whole ADR implementation makes sense only if it is proactively maintained (ADRs should be updated from time to time as part of the incorporated JAD/Architectural review process). 
   • Along with the ADR files, the referenced/linked documentation should be updated as the architectural / code changes are being done. This is needed because the documentation should reflect the latest updated changes.
2. Education
   • Implementing the ADRs need an additional step of maintaining and validating the decisions taken however that comes with all the benefits as below :
     1. ADR results in a crisp version of reviewed architecture.
     2. ADR helps in making the foundation of architecture stronger.
     3. ADR firms up the system design and the related decisions regarding the same.
   • However, the team members should be educated that the purpose of ADR is to not block/slow down the development process but to document “whatever” the decision was taken and move ahead further to implementing the same.
   • This way, the choices made as part of the decision get recorded and their implementation status gets tracked.

Appendix – What does an ADR look like ?

Scenario

The above ADR sample is created by the Development team for replacing the current ORM in the product (PrismaORM) with a new ORM (TypeORM).