BT

Facilitating the Spread of Knowledge and Innovation in Professional Software Development

Write for InfoQ

Topics

Choose your language

InfoQ Homepage Articles A Simple Framework for Architectural Decisions

A Simple Framework for Architectural Decisions

This item in japanese

Bookmarks

Key Takeaways

  • A framework for making architectural decisions can provide clarity on the process of decision-making and who should be involved. 
  • An internal Technology Radar can help teams understand the technology landscape and make informed decisions about which technologies to use. 
  • Technology Standards can ensure broader consistency of crosscutting concerns and reduce the risk of suboptimal adoption of new technologies. 
  • Finally, Architecture Decision Records (ADRs) can capture particular decisions that follow the Standards and the Radar and provide a historical record of their reasoning
  • These methodologies combined together satisfy all the needs around architectural decision governance and give a simple framework to use
     

A Simple Framework for Architectural Decisions

Software engineers must make architectural decisions to proceed with the development. Can we use Python instead of Java for our new microservice? Can we use another bundler when developing our new frontend library? Should I agree on the repository structure with my manager or other teams?

Should I use snake_case or camelCase when I am designing the REST API? The company needs to establish a clear framework for making those decisions, who needs to be involved, and where to find information about already-done decisions. 

It’s essential to make such a framework right, as it will define how much freedom and autonomy different teams have. This should align with the business’s needs and the company culture you are trying to build at a given stage.

This can impact how different leadership roles are perceived, the role of managers and individual contributors in technical decisions, and the level of empowerment at different career levels. While each company will pick different responsible people and different degrees of team autonomy according to its organizational boundaries, maturity, and needs, the framework may need very similar building blocks.

In this article, I’d like to share key building blocks which such a framework for making architectural decisions could have, based on my recent work experience across organizations of different scales. These building blocks include your own Tech Radar, Technology Standards, and Architecture Decision Records (ADRs).

Building your own Technology Radar

Some may know Thoughtworks, who initially established their Technology Radar. Thoughtworks captures and publishes what they see in the field with their customers across the industry.

Similarly, you can build your own radar showing the maturity of different technologies, tools, and methodologies your company uses or plans to use. A Technology Radar is a visual representation of your company’s current and desired technology stack.

You should make your definition of different stages—assess, trial, adopt, and hold, as well as the process of how a given technology should move through those stages. 

heycar Technology Radar example

At heycar, we use the stages in the following way. At first, new technology is in Assess, meaning it’s actively researched and evaluated. The assessment state usually ends with a proof of concept and an extensive list of pros and cons of the technology usage in our environment. We then discuss outcomes with the respective internal community of practice or teams that may interact with it. If the list of arguments and proof of concept implementation is convincing, the next step is a controlled Trial period. During the Trial period, the technology is pioneered in production for a single use-case only. If that step is successful, we declare the technology Adopted and give any team a green light for further usage. If the new technology is superseding the previously used one, it might be needed to signal that. That’s precisely how we use the Hold status—for the technologies we no longer aim to use and have a replacement strategy.

The Radar helps teams to understand the technology landscape and make informed decisions about which technologies to use. If you keep the Radar updated, everyone in the company is aware of the latest state of technologies in use and their impact on the business.

Introducing internal Technology Standards

The second building block is introducing Technology Standards. Technology Radar captures techniques, platforms, tools, languages and frameworks, and their level of adoption across an organization. However, this may not cover all the needs. Establishing consistent practices for things that apply across different parts of the system can be helpful. For example, you might want to ensure all logging is done in the same format and with the same information included. Or, if you’re using a REST API, you might want to establish some conventions around how it should be designed and used, like what headers to use or how to name things. Additionally, if you’re using multiple similar technologies, it can be useful to guide when to use each one. Technology Standards define the rules for selecting and using technologies within your company. They ensure consistency, reduce the risk of adopting new technology in a suboptimal way, and drive consistency across the organization.

Who should be in charge of the standards? Technology Standards should be created and maintained by a cross-functional team of experts in relevant fields. They should be reviewed regularly and updated as needed to keep up with changes in the technology landscape. Teams should be encouraged to follow the standards and provide feedback on their effectiveness. The format can be different but would likely have detailed explanations and code examples. It can be more formal and follow, for instance, the RFC Format Framework, or be more casual, depending on your preferences and engineering culture. Zalando’s RESTful API and Event Guidelines are a good example of the publically shared internal Technology Standard. In addition to the API standard, you may want to introduce logging and monitoring, deployment, and QA standards.

Based on internal standards, you can create quality gates such as checking for the test coverage, integrating code linter checking for naming conventions or formatting, or fitness functions verifying your architecture or repository structure. A combination of automated checks, using standards during new joiners onboarding, code reviews, or pair programming will help ensure that standards are used and bring value. In addition to gates that check adherence to the standards, this is also a chance to discuss the value of platform engineering to create a paved road. Don’t simply tell people when they’ve done something wrong—make it easy to do the right thing by default.

Adopting Architecture Decision Records (ADRs) practice

The third building block for aligning architecture decisions is creating ADRs or lightweight RFCs. ADRs are a way of documenting architectural decisions and their reasoning. They provide a historical record of important decisions and help teams understand why a particular approach was chosen. An ADR should be created by the team responsible for making the architectural decision. They should include information such as the problem being solved, the alternatives considered, the decision made, and the reasoning behind it. They are immutable documents. When a given decision is revisited, it typically results in a new document being created. ADR practice is becoming increasingly popular, so major cloud providers such as AWS and GCP added it to their respective documentation.

While Technology Radar and Standards are supposed to give guidance and expected boundaries to the technical decisions, ADRs capture the reasoning and document the particular one-time decisions—reasons for creating a new service or package, introducing new technology, or any other major architecture change. ADRs are typically stored in a centralized repository or documentation tool and are accessible to all relevant teams. They also help new team members get up to speed on the overall architecture and reasons behind significant decisions. 

The ADR review process can be used for multiple purposes—reviewing and approving decisions and sharing knowledge. While it’s common to involve everyone affected in the ADR review, sharing it with more people increases overall architectural awareness across an organization. In addition, it’s useful to present ADRs in the internal tech circles to collect more feedback. Sometimes you may have an engineer who solved similar challenges in the past but is not directly working on them right now. 

Like for the first two pillars, the process covering the final say in finalizing ADRs and what decisions are considered major enough to require an ADR would be different for every organization. To avoid duplication, you may use ADRs to agree on particular design choices for building a new major system change while agreeing on a broader usage of languages, tools, and practices using the Radar and Standards. Having the internal Technology Radar and Standards in place, agreeing on an ADR should be a lean and straightforward exercise as the most substantial technological choices, and principles are already aligned. 

Conclusions

Together, the Technology Radar, Technology Standards, and ADRs form a framework that provides a clear and consistent approach to making architectural decisions, reducing the risk of new technology adoption and providing a historical record of important decisions. By establishing a framework for architectural decisions, teams can ensure that their technology stack is aligned with their business goals and that their teams have the information and guidance they need to make informed decisions.

The degree of freedom your team has, and the process to change the Radar, Standards, or ADRs, will shape your engineering culture. Some organizations aim for radical team autonomy, and some aim for high consistency and alignment, which are more restrictive. For example, a possible approach could involve your senior technical leaders in changes to the Radar and Standards, which guide further technical decisions and leave ADRs to the teams responsible for respective software functionality. You can pick the framework and adjust it to your company’s needs. 

About the Author

Rate this Article

Adoption
Style

Hello stranger!

You need to Register an InfoQ account or or login to post comments. But there's so much more behind being registered.

Get the most out of the InfoQ experience.

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Community comments

  • Concept that we should not forget about!

    by Mikhail Laptev,

    Your message is awaiting moderation. Thank you for participating in the discussion.

    The concept of ADR is quite an interesting one and extremely useful!
    That's great that I run into this article, as well as into links on those mainstreams like GCP or AWS. I've been playing with something similar, or, better to say, tried to push through something similar to ADR in my current and former team, usually as one of *.md documents being uploaded to github (at least in this case you can try to keep an eye on immutability), with all the conversation going in either google docs or github issues.
    It would be great to see, what would be the recommendations to keep ADR review process more convenient and more neat, consider that collaboration would land beyond just text, but includes diagrams, code snippets, etc.

  • Re: Concept that we should not forget about!

    by shane lee,

    Your message is awaiting moderation. Thank you for participating in the discussion.

    I store adrs in GitHub. Use the adr tool for creating records. Prs provide that nice review process. And once merged publish on an internal docs site using mkdocs. Similar to what backstage provides for its tech docs.

  • Good idea with Technical Radar for company

    by Andrey Malygin,

    Your message is awaiting moderation. Thank you for participating in the discussion.

    I liked the approach of visually showing a list of technologies that can be used freely and which ones with caution and agreement, I would also add a little context why the choice is this way, and ADR is just right for this

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

BT