Designing an architecture can be seen, like any other design activity, as a set of decisions, where each represents a point in the design space (defined by all the design choices), and succession of these decisions can be viewed as a (search) path through the design space. This leads us to two important observations.

It is not enough to document only the decisions that lead to the final design and not the design itself, because this would force the stakeholders, who need to know what the architecture is, to deduce it themselves.

In case of agile/iterative development the order of design decisions (the paths taken through the design space) matters, because in some place of the design space the next possible choices could be constrained, so that it becomes impossible to reach the desired state.

Designing an architecture (or “architecting”) can be seen, like any other design activity, as a set of decisions representing a path/trajectory in the design space (defined by all the choices that designer could make) that leads from the starting point to the final design (represented by a point in the design space), see H. A. Simon. The Sciences of the Artificial. The MIT Press, third edition, 1996. and D. Garlan, and M. Shaw, An Introduction to Software Architecture.

On the kinds of design decisions and their attributes in the architectural design of software systems see P. Kruchten, An Ontology of Architectural Design Decisions in Software-Intensive Systems.

There are two important questions related to this:

1. Is it enough to document only the design decisions taken during the architecture work, as a path to the final result?

   

To that we must answer, that although it is important to record/document all the design decisions, this documentation alone will not be sufficient to document the final architecture, because this would force each reader to “replay” all the steps taken by the architect to be able to find out what the architecture is looking like (i.e. build itself the final architecture). Couple of random examples from such decision sets, which show this problem: OpenAttestation and ADR Tool.

While this could be educationally a good exercise for introducing new team member to the architecture and the related reasoning, this will not be suitable for many other stakeholders, who need to see the whole architecture (as a possible input for their own decision making processes).

Therefore we need also a description of the final architecture provided possibly from different viewpoints that correspond to the different sets of concerns of different stakeholders, see P. Merson, P. C. Clements, F. Bachmann, L. Bass, D. Garlan, J. Ivers, R. Little, R. Nord, and J. A. Stafford, Documenting Software Architectures: Views and Beyond, 2nd Edition, 2010

2. Is the order of design decisions important or not – i.e. are all paths to a certain design through the design space equal?

   

To that we must answer with the usual “answer from architect” – it depends!

If we are doing the “dreaded” BDUF, then the order of design decisions is not important, because the steps from one point to another in the design space do not cost anything and any constraints on the steps between the two points in design space are due to the overall set of steps taken (due to the relationships between the design dimensions) independent of the order in which these steps are taken (see my thoughts on agile methods and architecture).

But if we are trying incrementally build the design, making the design decisions as we go, then the order of design decisions becomes very important, because if certain design decisions have been implemented, this will rule out some other design decisions in the future (due to the aforementioned relationships between the design dimensions) – we can literally “paint our-self in the corner”.

So to be successful in the agile (incremental development) and keep our options of choice as wide as possible, architect (or who-ever is the “master-builder”) must have the BDUF in his/hers “back pocket”, although there might be situations, where it’s better not to show this to the others who are involved in the journey.