If you open up something like Google Maps on your smartphone and do a search for Jersey, it will zoom into Jersey. This is great if you want to know what’s inside Software architecture diagram and what the various place names are, but if you’ve never heard of Jersey it’s completely useless.
A feature that has been built into Structurizr is that you can link components on a component diagram to code-level elements, which provides that final level of navigation from diagrams to code. Whatever tooling you use to create software architecture diagrams though, make sure that your diagrams reflect real structures in the code and that the mapping between diagrams and code is simple. My FREE The Art of Visualising Software Architecture ebook has more information on this topic. 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.
Did not find what they wanted? Try here
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. Although the software development industry has progressed in many ways, we seem to have forgotten some of the good things that these older approaches gave us. 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 software architecture of a software system. Abandoning UML is all very well but, in the race for agility, many software development teams have lost the ability to communicate visually too.
Colour-coding is usually not explained or is often inconsistent. Key relationships between diagram elements are sometimes missing or ambiguous. Generic terms such as “business logic” are often used. Levels of abstraction are often mixed. Diagrams often try to show too much detail. Diagrams often lack context or a logical starting point. 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 shows 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. A context diagram can be a useful starting point for diagramming and documenting a software system, allowing you to step back and look at the big picture. Draw a simple block diagram showing your system as a box in the centre, surrounded by its users and the other systems that it interfaces with. IT and digital sector in Jersey and Guernsey, the two largest of the Channel Islands. At the most basic level, it’s a content aggregator for local tweets, news, blog posts, events, talks, jobs and more.
Here’s a context diagram that provides a visual summary of this. Detail isn’t important here as this is your zoomed out view showing a big picture of the system landscape. It’s the sort of diagram that you could show to non-technical people. Once you understand how your system fits in to the overall IT environment with a context diagram, a really useful next step can be to illustrate the high-level technology choices with a containers diagram. Essentially, what I call a container is anything that can host code or data. The following diagram shows the logical containers that make up the techtribes.
All data is stored either in a MySQL database, a MongoDB database or the file system. It’s worth pointing out that this diagram says nothing about the number of physical instances of each container. Following on from a containers diagram showing the high-level technology decisions, I’ll then start to zoom in and decompose each container further. However you decompose your system is up to you, but I tend to identify the major logical components and their interactions. This is about partitioning the functionality implemented by a software system into a number of distinct components, services, subsystems, layers, workflows, etc. As illustrated by the containers diagram, techtribes.