How to write architectural design principles that scale decision making

13 June 2021

A system is more than just a collection of services and applications. It is a distributed collaboration between stakeholders, users, processes, developers, software, infrastructure, suppliers, and data. This is difficult to control directly, but you can influence the development of a system by establishing a clearly defined and widely understood set of architectural principles.

These principles describe the common set of underlying beliefs about system design. They can help to create a common sense of purpose and lay down some basic guidelines for decision making.

In this sense, architectural principles can help to scale architectural decision making by providing high-level guidance to everybody involved in development. Software engineering teams make small, local decisions all the time. Ideally, you want a set of principles that can help to ensure that this decision making does not diverge too far from any wider strategy.

Reflecting consensus

Architectural principles are a foundational element of TOGAF, which describes them as:

"...general rules and guidelines, intended to be enduring and seldom amended, that inform and support the way in which an organization sets about fulfilling its mission."

TOGAF expects architectural principles to support decision making by reflecting a level of consensus in an organisation. This consensus is a key characteristic of architectural principles, as it allows them to represent what really matters to an organisation.

The act of drafting a set of architectural principles can be an opportunity to forge consensus, confront disagreement, and win support for specific strategies. They can be used to help bind everybody involved in development into a common purpose and communicate a statement of intent to the wider organisation. If you can win widespread support for a core set of architectural principles, then it can help to ensure that everybody is swimming in the same direction.

Consensus normally requires that principles be derived directly from the wider business vision and strategy. It is this relationship to the wider mission that gives architectural principles their strength. If a set of architectural principles follow on naturally and logically from the business strategy, they will feel more credible and provide a more solid foundation on which to resolve disputes.

Over time, a good set of principles can help to define how you make decisions, i.e. the posture of architecture within the organisation. This can include the behaviours that underpin good architectural decision-making, enshrining qualities such as openness, collaboration, and pragmatism.

Getting the granularity right

The implication here that principles are broad, high-level statements that deal in general strategic themes. This is distinct from more specific standards or guidelines that provide explicit directions for teams to follow.

For example, an architectural principle might state that the organisation should favour open standards, but it won’t state which standards to adopt. The desire to build loosely coupled services might be a principle, but the various patterns and technologies that ensure this are best expressed in design guidelines.

There is a risk that principles become so large as to be nebulous. Exhorting engineering to “make it scalable” is just stating the obvious unless there is a specific underlying business context, such as the expectation of rapid and unpredictable growth. You need to ensure that stakeholders can relate to the principles and recognise the business drivers that lurk underneath. This requires clear language, precise definitions, and careful consistency.

You also want to limit the number of principles to ensure that your architecture remains flexible. TOGAF recommends somewhere between ten and twenty principles, and this is a reasonable range to define the main strategic priorities for an architecture.

Empty slogans and cheesy catchphrases

Given that we are dealing with high-level themes, it can be easy for principles to descend into empty slogans. Principles are not an opportunity to echo brand values or propagate motivational catchphrases. Marketing slogans that exhort teams to “build great applications” that “thrill our customers” will not be of much use when engineers are disagreeing about technology choices.

Principles need to be rooted in the kinds of practical issues that crop up in day-to-day decision making. They need to be specific, provide clear guidance any maybe even impart a little bit of wisdom. If your principles are too obvious then they will be ignored as empty slogans.

It can be tempting to boil principles down to a set of slogans that resonate and are easy to remember. However, context is important here and this can be difficult to capture in a slogan. When drafting a set of principles, it can be helpful to include a more detailed rationale for each principle, including a statement of the implications it has for wider development.

For example, stating that “data should be accessible” needs careful qualification. It may speak more to technical flexibility in terms of protocols and formats rather than being readily available to all users. Access to data may not necessarily involve the right to modify or share the data. There may also be a host of governance restrictions that users should be willing to accommodate.

Evolving principles

A set of principles shouldn’t change very often, but they are not completely immutable. Strategies do evolve and the ground may shift. You should be prepared to take a flexible approach and develop your principles in response to changing circumstances.

Architectural principals aren’t just for Christmas. They gain their power through repetition. You need to refer to them constantly and make sure that they continue to be reflected in your work. They are not laws that require specific enforcement, but it should be obvious when they are not being observed.