Sunday, May 5, 2013

NoUML or perhaps LowUML

Recently I attended ITARC 2013 where there was a very interesting seminar by Simon Brown regarding Software Architecture Sketches and NoUML (see his article on InfoQ). This seminar led me to further consider how we effectively communicate and visualize our architectures at both Enterprise and Solution level.

Traditionally when we were building software systems we often had a very homogeneous team of people working with the development. Often a team of technical developers and we may have worked on a basis where the architecture was driven from a technology perspective. In this respect the stakeholders in IT were often technical in nature and communication of the architecture between these stakeholders would be performed using models such as UML. This was suitable since the stakeholders often had experience of these models from their education and were familiar with the terms and concepts.

In recent years the landscape has changed. Architectures are built with the Business as a driver with a view to interlocking business and IT. The adoption of Agile also plays a part making the development process transparent and also employing skills in cross-functional teams.
The result is that we have a significant increase in stakeholders in the architecture many of whom may be non-technical and who all have different perspectives on the given Product or Enterprise. At the same time need an effective way to communicate and understand the architecture for all perspectives.

Difficulties with UML

Firstly we have to consider what we mean with "the architecture". When do we stop with an architecture and start with a design? We could spend a lot of time debating this but the following quote does a pretty good job of summarizing what "the architecture" represents.

"Architecture represents the significant design decisions that shape a system, where significant is measured by cost of change."(Grady Booch)

This is important because UML still has a place in software development when we are working with lower level abstractions since we require significantly more details in our communication. So we are still likely to produce class diagrams, sequence diagrams and other UML diagrams to help communicate complex detail. We can still use these in "the architecture" but these feel more like "designs" than architecture. This is why I prefer the term LowUML rather than NoUML.

It is perhaps the complexity and more rigid notation which makes UML a difficult tool to use when communicating and architecture at a higher level of abstraction with many stakeholders. One problem is that many stakeholders, even in the development teams, simply don't know UML and have no ambition to learn it either. Such stakeholders may be non-technical or skilled in a field which does not require knowledge of the details but does require an understanding of the architecture. This is where simpler modeling methods such as "sketching" are more useful.

Separating the Levels of Abstraction

Part of making the architecture easier to understand for different stakeholders is the separation of the levels of abstraction. This will allow stakeholders to view the architecture from at a level of detail which is easy for them to understand. Simon Brown suggests using the following levels of abstraction.

  • Context - shows IT landscape over the enterprise or for a particular solution, mainly shows systems and actors
  • Container - the high level technology choices, where containers are often execution environments such as databases, application servers or file systems
  • Component - the relationships between components where a component can be thought of as a service or logical unit exposed through a known interface.
  • Class - a description of the classes in a component adhering to object oriented principles.

The "Class" level of abstraction is a low level and in this case I would recommend continued use of UML rather than creation your own notation.

Note that these diagrams are very focused on the "structure" of the architecture and are not intended to processes or detailed behavior.

Define Your Notation 

When using sketches in an architecture we can often use a number of symbols, line styles or colours in our diagram to improve understanding.

However we can often forget to explain our notation and while the diagram may be clear to the author it may not be so clear to the stakeholders. So it is important to have a clear explanation of the notation for the stakeholders. An example notation is shown in the diagram opposite, and this notation will be used in the following diagrams.
We should keep the notation simple so it can be easily understood by the different stakeholders. If we find ourselves adding more complex notation this is a warning sign. The purpose here is to create an easy to understand communication medium, not to create our own version of UML.
When we reach the lower levels of abstraction and require need a more powerful notation we can switch over to UML diagrams. We still want to use UML but at the lower levels of abstraction.

Context Level of Abstraction

The context level of abstraction is the highest level of abstraction and shows the system landscape. This is the level we want to use with Business and Non-Technical stakeholders. We can use a context diagram to describe both the Enterprise and the Solution landscape.

In the example below we can see an Enterprise Landscape containing a number of systems we may commonly find in any Enterprise. Most of the systems in the diagram are Internal (the Enterprise maintains control of the system) and only the Credit Check system is External (perhaps provided off-site by a vendor).
Notice that in this diagram we only indicate that there are relations between the systems and actors, we do not go into detail regarding what that relation is.

If we are working with the architecture of a specific solution we can also detail the Solution Landscape. This shows a specific solution and it's associated systems/actors. This basically focuses on a section of the Enterprise Landscape. In the example below we can see the landscape for the Web Booking system.

Keeping these diagrams simple will allow to communicate a level of the architecture to many stakeholders. At the same time these diagrams do not contain details so if we are looking for technical details or more information about the relations we have to lower the level of abstraction.

Container Level of Abstraction

Containers show the high level technology selections on a per System basis. In these diagrams we are moving away from the Business/Non-Tech stakeholders towards those who have an interest in the technology. So this is the domain of the Architects, Development  Teams and Operation Teams. The following is an example of containers for the "Web Booking" solution.

We can now see the technologies that will be used in the architecture and the relation between the containers, systems and actors. At this level we may also want to detail perhaps technology protocols used in the relation, such as SOAP or SQL, these are not shown in the above diagram.

Component Level of Abstraction

At the component level we are reaching the lower levels of abstraction in the solution architecture. It is here that we start to define our logical units or services on a per Container basis. There can also be more than one level of abstraction for components and this is perhaps where it gets more difficult in knowing where to draw the line between the simple notation and a more advanced notation such as UML. At this level we are communicating to technical stakeholders often in the development team. Below is an example for the "Booking Web Server" container.

As we can see this is where we start to hang more detail on the architecture. Not only are the components specified but the relations between the Components, Containers, Systems and Actors indicate direction and we give some idea of the data that is involved in the relation.
It is important not to over complicate the diagram. If we have a component which is complex we can create a new diagram specifically for that component and decide whether it is more suitable to use a UML notation for modelling or if the simple notation is sufficient.

Keeping Things Simple

One way to try and limit the complexity in diagrams is to put a boundary on the size of the diagram. This is not always possible but a good rule is to try and keep the size of each diagram limited to fitting on a single sheet of A3 paper.

Not Only Diagrams

The diagrams are probably not sufficient on their own to describe the architecture so textual description will also be required in formal documentation. However the diagrams as working documents can be used on their own. It can also be an idea to tag "responsibilities" to Systems, Containers and Components. This can help to build a better architecture since we can easily see if we have duplicating responsibilities over Systems, Containers or Components.

Make the Architecture Visible

Architectures are often documented, but lack a high level of visibility in the organisation or team. If we want to consider the architecture we often have to look it up in some document which is archived somewhere or on a web page.
 A better approach is to ensure that the architecture is constantly visible so that stakeholders can use it as a reference point when discussing proposals or changes. This simply involves pinning up the architecture diagrams in a team room so they are constantly visible and can actively be used in discussions.


There is a need today to communicate Enterprise and Solution architectures to a broad spectrum of stakeholders. Many of these stakeholders do not have an understanding of UML, and this makes UML a difficult tool to use at higher levels of abstraction.

Using a simpler notation makes it easier to communicate the architecture and using well defined levels of abstraction allows us to target different stakeholder perspectives. This also helps us easily visualise the architecture and use it as a daily reference point for development teams.

When we reach the lower levels of abstraction, closer to design, a simple notation may not be sufficient and it is at this point we can switch to using a notation such as UML which can help describe complex designs.

1 comment: