Agile software Architecture design document style: (Sketches and no UMLs)

Http://www.infoq.com/articles/agile-software-architecture-sketches-NoUML

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 it to introduce transparency because anybody can see, at a G Lance, a high-level snapshot of the current progress. As an industry, we ' ve become pretty adept at visualising we 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 soft Ware development process. Agility is on moving fast and this requires good communication, but it's surprising that many teams struggle to effecti Vely communicate the design of their software.

Prescribed methods, process frameworks and formal notations

If you look up a few years, structured processes and formal notations provided a reference point for both the software D Esign process and how to communicate the resulting designs. Examples include the Rational Unified Process (RUP), structured Systems analysis and Design Method (SSADM), the Unified Mo Delling Language (UML) and so on. Although the software development industry has moved on many ways, we seem to having forgotten some of the good things th At these older approaches gave us. In today's world of agile delivery and lean startups, some software teams has lost the ability to communicate what it is They is 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 are contributing to the same end-goal, you need to being able to effectively communicate The vision of what it was you ' re building. And if you want agility and the ability to move fast, you need to being able to communicate that VIsion efficiently too.

Abandoning UML

As an industry, we does have the Unified modelling Language (UML), which are a formal standardised notation for communicating The design of software systems. I do the UML myself, but I-tend to use it sparingly-sketching out any important low-level design aspects of a SOF Tware System. I don ' t find the UML works well for describing the high-level software architecture of a software system and while it ' s p Ossible to debate this, it's often irrelevant because many teams has 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 ' ts make much sense Unless they is 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 t Hey is presenting what's on the sketches or whether they is presenting what's still in their head.

Related Vendor Content

Why Poor performing Apps Don ' t last Longgartner Magic Quadrant for application performance Monitoringfrom relational Datab ASEs to Riak NoSQL for high availability and Scalecloud Migration:thin Ice or Solid Ground? Meeting the challenges of unstructured Data

(Click on the image to enlarge it)

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

• Colour-coding is usually isn't explained or is often inconsistent.
• The purpose of diagram elements (i.e. different styles of boxes and lines) are often not explained.
• Key relationships between diagram elements is sometimes missing or ambiguous.
• Generic terms such as "business logic" is often used.
• Technology choices (or options) are usually omitted.
• Levels of abstraction is 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 is many pitfalls associated with communicating software D Esigns in the This. My approach is to use a small collection of simple diagrams, each show a different part of the same overall story. In order-to-do-though, you need-agree on a simple-to-think about the software system-you ' re building. Assuming an object oriented programming language, the the-the-the-I like to-think about a-software system is as follows ... a Software system is made up of a number of containers, which themselves was made up of a number of components, which in Tu RN is implemented by one or more classes. It's a simple hierarchy of logical building blocks so can be used to model most of the software systems that I ve Encoun tered.

• Classes: In a OO world, Classes is the smallest building blocks of our software systems.
• Components: components (or services) is typically made up of a number of collaborating classes, all sitting Behi nd 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 is executed or where data resides. This could is anything from a Web or application server through to a rich client application, database or file system. Containers is typically the things that need to being running/available for the software system to work as a whole. The key thing about understanding a software system from a containers perspective are that any Inter-container communicatio n 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 the this set of abstractions to think on a software system, we can now draw a number of simple boxes and lines Ske Tches to summarise the static structure of this software system as follows (you can see some examples on Flickr):

2. 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, the software system interfaces with. Detail isn ' t important here's your zoomed out view showing a big picture of the system landscape. The focus should is 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's could show to non-technical people.
4. Containers diagram: A high-level diagram showing the various Web servers, application servers, standalone Applica tions, databases, file systems, etc, make up your software system, along with the relationships/interactions between T Hem. This was 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.
6. Components diagrams: A diagram (one per container) showing the major logical components/services and their relati Onships. Additional information such as known technology choices for component implementation (e.g. Spring, Hibernate, Windows Comm Unication Foundation, F #, etc) can also is added to the diagram in order to ground the design in reality.
8. Class diagrams: Optional level of detail and I would typically draw a small number of high-level UML CL Diagrams if I want to explain how a particular pattern or component would be (or have 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 This 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 Prese NT the software from a number of different levels of abstraction. Important point because it's not just software developers within the team that need information about the S Oftware. There is other stakeholders and consumers too; Ranging from non-technical domain experts, testers and management through to technical staff on operations and support fun Ctions. For example, a diagram showing the containers are particularly useful for people like operations and support staff this WAN T some technical information about your software system, but don ' t necessarily need to know anything about the inner Worki Ngs.

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 provi Ding some organisational ideas and guidelines rather than creating a prescriptive standard. The goal here's to help teams communicate their software designs on an effective and efficient it's rather than creating a Nother Comprehensive modelling notation. It ' s worth reiterating that informal boxes and lines sketches provide flexibility at the expense of diagram consistency be Cause you ' re creating your own notation rather than using a-like UML. My advice here's to being conscious of colour-coding, line style, shapes, etc and let a set of consistent notations evolve N Aturally within your team. Including a simple key/legend on each diagram to explain the notation would help too.

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

"Just enough" up front design

As a final point, Grady Booch have 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 Softwa Re system. Therefore, in addition-helping teams with effective and efficient communication, adopting the approach to diagramming can also help software teams this struggle with either doing too much or too little up front design. Starting with a blank sheet of paper, many software systems can is 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 is a quick and easy task, when do well, can really help to introduce t Echnical leadership and instil a sense of a shared technical vision, the whole team can buy into. Sketching ShouLD be a skill in every software developer ' s toolbox. It's a great to visualise a solution and communicate it quickly plus it paves the the-for collaborative design and COL Lective code ownership.

About the Author

Simon Brown lives in Jersey (Channel Islands) and works as a independent consultant, specialising in software ar Chitecture, technical leadership and the balance with agility. Simon regularly speaks at international software development conferences and provides consulting/training to software team s 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 (a e-book that's being published incrementally through Leanpub). He still writes code too. Simon can is found on Twitter at @simonbrown.

Agile software Architecture design document style: (Sketches and no UMLs)