New Early adopter or innovator? InfoQ has been working on some new features for you. Learn more

Agile Software Architecture Sketches and NoUML

| Posted by Simon Brown on Apr 16, 2013. Estimated reading time: 9 minutes |

If you're working in an agile software development team at the moment, take a look around at your environment. Whether it's physical or virtual, there's likely to be a story wall or Kanban board visualising the work yet to be started, in progress and done. Visualising your software development process is a fantastic way to introduce transparency because anybody can see, at a glance, a high-level snapshot of the current progress. As an industry, we've become pretty adept at visualising our software development process over the past few years although it seems we've forgotten how to visualise the actual software that we're building. I'm not just referring to post-project documentation, this also includes communication during the software development process. Agility is about moving fast and this requires good communication, but it's surprising that many teams struggle to effectively communicate the design of their software.

Prescribed methods, process frameworks and formal notations

If you look back a few years, structured processes and formal notations provided a reference point for both the software design process and how to communicate the resulting designs. Examples include the Rational Unified Process (RUP), Structured Systems Analysis And Design Method (SSADM), the Unified Modelling Language (UML) and so on. Although the software development industry has moved on in many ways, we seem to have forgotten some of the good things that these older approaches gave us. In today's world of agile delivery and lean startups, some software teams have lost the ability to communicate what it is they are building and it's no surprise that these teams often seem to lack technical leadership, direction and consistency. If you want to ensure that everybody is contributing to the same end-goal, you need to be able to effectively communicate the vision of what it is you're building. And if you want agility and the ability to move fast, you need to be able to communicate that vision efficiently too.

Abandoning UML

As an industry, we do have the Unified Modelling Language (UML), which is a formal standardised notation for communicating the design of software systems. I do use UML myself, but I only tend to use it sparingly for sketching out any important low-level design aspects of a software system. I don't find that UML works well for describing the high-level software architecture of a software system and while it's possible to debate this, it's often irrelevant because many teams have already thrown out UML or simply don't know it. Such teams typically favour informal boxes and lines style sketches instead but often these diagrams don't make much sense unless they are accompanied by a detailed narrative, which ultimately slows the team down. Next time somebody presents a software design to you focussed around one or more informal sketches, ask yourself whether they are presenting what's on the sketches or whether they are presenting what's still in their head.

(Click on the image to enlarge it)

Abandoning UML is all very well but, in the race for agility, many software development teams have lost the ability to communicate visually too. The example NoUML software architecture sketches (above) illustrate a number of typical approaches to communicating software architecture and they suffer from the following types of problems:

  • Colour-coding is usually not explained or is often inconsistent.
  • The purpose of diagram elements (i.e. different styles of boxes and lines) is often not explained.
  • Key relationships between diagram elements are sometimes missing or ambiguous.
  • Generic terms such as "business logic" are often used.
  • Technology choices (or options) are usually omitted.
  • Levels of abstraction are often mixed.
  • Diagrams often try to show too much detail.
  • Diagrams often lack context or a logical starting point.

Some simple abstractions

Informal boxes and lines sketches can work very well, but there are many pitfalls associated with communicating software designs in this way. My approach is to use a small collection of simple diagrams that each show a different part of the same overall story. In order to do this though, you need to agree on a simple way to think about the software system that you're building. Assuming an object oriented programming language, the way that I like to think about a software system is as follows ... a software system is made up of a number of containers, which themselves are made up of a number of components, which in turn are implemented by one or more classes. It's a simple hierarchy of logical building blocks that can be used to model most of the software systems that I've encountered.

  • Classes: in an OO world, classes are the smallest building blocks of our software systems.
  • Components: components (or services) are typically made up of a number of collaborating classes, all sitting behind a coarse-grained interface. Examples might include a "risk calculator", "audit component", "security service", "e-mail service", etc depending on what you are building.
  • Containers: a container represents something in which components are executed or where data resides. This could be anything from a web or application server through to a rich client application, database or file system. Containers are typically the things that need to be running/available for the software system to work as a whole. The key thing about understanding a software system from a containers perspective is that any inter-container communication is likely to require a remote interface such as a web service call, remote method invocation, messaging, etc.
  • System: a system is the highest level of abstraction and represents something that delivers value to, for example, end-users.

Summarising the static structure of your software with NoUML

By using this set of abstractions to think about a software system, we can now draw a number of simple boxes and lines sketches to summarise the static structure of that software system as follows (you can see some examples on Flickr):

  1. Context diagram: a very high-level diagram showing your system as a box in the centre, surrounded by other boxes representing the users and all of the other systems that the software system interfaces with. Detail isn't important here as this is your zoomed out view showing a big picture of the system landscape. The focus should be on people (actors, roles, personas, etc) and software systems rather than technologies, protocols and other low-level details. It's the sort of diagram that you could show to non-technical people.
  2. Containers diagram: a high-level diagram showing the various web servers, application servers, standalone applications, databases, file systems, etc that make up your software system, along with the relationships/interactions between them. This is the diagram that illustrates your high-level technology choices. Focus on showing the logical containers and leave other diagrams (e.g. infrastructure and deployment diagrams) to show the physical instances and deployment mappings.
  3. Components diagrams: a diagram (one per container) showing the major logical components/services and their relationships. Additional information such as known technology choices for component implementation (e.g. Spring, Hibernate, Windows Communication Foundation, F#, etc) can also be added to the diagram in order to ground the design in reality.
  4. Class diagrams: this is an optional level of detail and I will typically draw a small number of high-level UML class diagrams if I want to explain how a particular pattern or component will be (or has been) implemented. The factors that prompt me to draw class diagrams for parts of the software system include the complexity of the software plus the size and experience of the team. Any UML diagrams that I do draw tend to be sketches rather than comprehensive models.

(Click on the image to enlarge it)

A single diagram can quickly become cluttered and confused, but a collection of simple diagrams allows you to easily present the software from a number of different levels of abstraction. And this is an important point because it's not just software developers within the team that need information about the software. There are other stakeholders and consumers too; ranging from non-technical domain experts, testers and management through to technical staff in operations and support functions. For example, a diagram showing the containers is particularly useful for people like operations and support staff that want some technical information about your software system, but don't necessarily need to know anything about the inner workings.

Organisational ideas, not a standard

This simple sketching approach works for me and many of the software teams that I work with, but it's about about providing some organisational ideas and guidelines rather than creating a prescriptive standard. The goal here is to help teams communicate their software designs in an effective and efficient way rather than creating another comprehensive modelling notation. It's worth reiterating that informal boxes and lines sketches provide flexibility at the expense of diagram consistency because you're creating your own notation rather than using a standard like UML. My advice here is to be conscious of colour-coding, line style, shapes, etc and let a set of consistent notations evolve naturally within your team. Including a simple key/legend on each diagram to explain the notation will help too.

There seems to be a common misconception that "architecture diagrams" must only present a high-level conceptual view of the world, so it's not surprising that software developers often regard them as pointless. In the same way that software architecture should be about coding, coaching and collaboration rather than ivory towers, software architecture diagrams should be grounded in reality too. Including technology choices (or options) is a usually a step in the right direction and will help prevent diagrams looking like an ivory tower architecture where a bunch of conceptual components magically collaborate to form an end-to-end software system.

"Just enough" up front design

As a final point, Grady Booch has a great explanation of the difference between architecture and design where he says that architecture represents the "significant decisions", where significance is measured by cost of change. The context, containers and components diagrams show what I consider to be the significant structural elements of a software system. Therefore, in addition to helping teams with effective and efficient communication, adopting this approach to diagramming can also help software teams that struggle with either doing too much or too little up front design. Starting with a blank sheet of paper, many software systems can be designed and illustrated down to high-level components in a number of hours or days rather than weeks or months. Illustrating the design of your software can be a quick and easy task that, when done well, can really help to introduce technical leadership and instil a sense of a shared technical vision that the whole team can buy into. Sketching should be a skill in every software developer's toolbox. It's a great way to visualise a solution and communicate it quickly plus it paves the way for collaborative design and collective code ownership.

About the Author

Simon Brown lives in Jersey (Channel Islands) and works as an independent consultant, specialising in software architecture, technical leadership and the balance with agility. Simon regularly speaks at international software development conferences and provides consulting/training to software teams at organisations across Europe, ranging from small startups through to global blue chip companies. He is the founder of Coding the Architecture (a website about pragmatic, hands-on software architecture) and the author of Software Architecture for Developers (an e-book that is being published incrementally through Leanpub). He still writes code too. Simon can be found on Twitter at @simonbrown.

Rate this Article

Adoption Stage

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.

Tell us what you think

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

Email me replies to any of my messages in this thread

sketches by Nikola Stjelja

I do generally agree that for some architectural designs uml is not the best tool. I've often found it works best for designing small slices of the system which are given directly to developers for implementation while high level ideas and processes work best as freeform sketches (I actually use visio for that).

What about Processes? by Thomas Schröder

Usually these diagrams are all only a static view of the system. Do you use something special to visualise flows, like Shopping Cart Checkout?

UML is a Pattern Library by Adam Nemeth

The main use of UML is not that it's a visual language everyone is ought to learn. A visual language should be readable for anyone.

The main use of UML was for me that it's a Pattern Language through its diagrams, it has a "problem-solution" form. Example:

Do you need to show how the system will spread accross multiple servers? What's important, the application components used or the files? The physical connections or the protocol? Depending on these, use a Deployment DIagram or a Component Diagram.

UML taught me what to look at when facing certain problems.

Unfortunately, because standard UML expects its readers to be intimately familiar with its visual vocabulary, and doesn't really deal with aesthetics, it's unusable for client consumption, so "visual stereotyping" has to be used.

But Thomas Schröder is right:

The important part of UML was never structural, but behavioral modeling.

Somehow we forgot that class diagrams - especially those mixed class diagrams in use at a lot of places - are verging on the edge of impracticality.

The nuissance differences between an activity diagram and a state diagram, a communication diagram or a sequence diagram is what made UML really important.

Unfortunately, as it's taught in a kind of mistery, and as the profession of development abandoned design entirely (such that it allows other professions and even layman clients to actually design the software from nearly every perspective) we're left with a bunch of code whic is just what it is: a bunch of code, hopefully written in a way that it acts as someone else intended.

Re: sketches by Simon Brown

I also use tools like Visio, OmniGraffle, etc ... photos of sketches are great but often I want something that looks neater to share with people. Also, Visio diagrams can be easily modified.

Re: What about Processes? by Simon Brown

That's right, yes, these diagrams do only show a static view of the system. I tend to use UML activity diagrams to illustrate workflows, processes, etc and UML sequence/collaboration diagrams to show how important use cases, stories, etc are implemented. Although sequence and collaboration diagrams are usually used to represent the flow of messages between objects, there's no reason why you can't step up one level of abstraction and think about components, or further to show container interactions.

Re: UML is a Pattern Library by Simon Brown

I still think the best UML book I've ever read is Martin Fowler's "UML Distilled" ... the early 1.x version. It was short, simple and the notation could be explained to non-technical people if needed. Except for the difference between aggregation and composition, of course!

To pick up on your last point about "just a bunch of code", this is something that I'm looking into at the moment. If you're interested too, I've written a blog entry called Mapping software architecture to code and George Fairbanks talks about something he refers to as architecturally evident coding. Writing code that better maps onto the architecture allows the type of diagrams I talk about above to be generated automatically.

Please find a better name by Jeff Heon

I find NoSQL a bad enough name already. Now I'm seeing NoUML and noBackend popping up. Argh.

Not True by Anthony DaSilva Jr

BDUF and UML aren't necessarily welded together. Just because they often were/are doesn't mean you have to throw out the baby with the bathwater. There's always a backlash against any powerfully complex technology like UML that takes a considerable investment of time to learn. The beauty of UML is that it's a standard and you can use whatever level of detail you need/want to communicate your designs/architectures.

Nevertheless, I do like your work and I salute you for finding a nice NoUML niche to exploit.

Software architecture is not just "static structure" of the system by Suman Pradhan

Software architecture is not just “static structure” of the system. It represents the overall structure and foundation (including why, what, how and where domains of solution space) of a software system in a run-time environment in order to satisfy the functional requirements and achieve a desired set of quality attributes. Your article did a very good job in explaining the design concerns in terms of coding implementation from developer perspective, but does not provide enough details about other “architecture views” (process flow, deployment view etc.) from operation, business stakeholder’s perspective.

Recently I posted an article on IT architecture development framework in InfoQ website. In that article, I’ve explained how IT architecture (including software architecture) relates to “building architecture” and its relationship with quality, design and other areas.

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

Email me replies to any of my messages in this thread

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

Email me replies to any of my messages in this thread

9 Discuss

Login to InfoQ to interact with what matters most to you.

Recover your password...


Follow your favorite topics and editors

Quick overview of most important highlights in the industry and on the site.


More signal, less noise

Build your own feed by choosing topics you want to read about and editors you want to hear from.


Stay up-to-date

Set up your notifications and dont miss out on content that matters to you