Over a million developers have joined DZone.
{{announcement.body}}
{{announcement.title}}

Showing Your Software Architecture: Visual Communication

DZone's Guide to

Showing Your Software Architecture: Visual Communication

Documenting software architecture is a difficult thing to do. There are several ways of going about it and each presents different aspects of the system with different audiences in mind.

· DevOps Zone
Free Resource

Download “The DevOps Journey - From Waterfall to Continuous Delivery” to learn about the importance of integrating automated testing into the DevOps workflow, brought to you in partnership with Sauce Labs.

Talking about documenting in software development is usually a challenge... and also just pretty boring. Nonetheless, in order to have good communication with stakeholders, we have to document our systems properly. 

However, when beginning to write, we often find ourselves stumped, asking ourselves: What diagram should we draw? What notation? How much detail? Who is the audience for these?

Then, after a while, we might end up with this.

Image title

In this article, we'll present four levels of useful diagrams that all software systems should have. See more details here: https://leanpub.com/visualising-software-architecture/read

Level 1 – Context Diagram

A context diagram is useful to provide a visual summary of what software system we are creating, who is using it, and how it fits within an existing environment.

Structure

In this diagram, you don't have care about details like technologies, protocols, and other low-level details. The focus here is people and the software system. 

Look at this example below.

Image title

Audience: Technical and nontechnical people, tied or not tied to the software development team.

Level 2 – Container Diagram

Now that you know how the system fits into the overall environment with a context diagram, we can go ahead and provide a few more details about our technology choices.

Structure

The container diagram, as stated above, shows our choices of technologies and how the containers communicate with one another.

Look at this example below.

Image title

Audience: Technical people tied or not tied to the software development team, including operational and support staff.

Level 3 – Component Diagram

Once you have a high-level technology view about your software, you can continue by zooming in and decomposing each container to reveal the deeper components involved.

The purpose of this diagram is to identify what components/services the system is made up of, how the system works at a high level, and if all of them reside in a container.

Structure

Don't be concerned about details, if you don't have it, just add what you know.

Here an example:

Image title

Audience: Technical pople within the software developement team.

Level 4 – Class Diagram

To finish this series, the last level of detail we'll cover is the class diagram. The intent here is to show the internal details of a single component.

Structure

You have to be careful with class diagram because it's very easy to include a lot of details, especially if you use auto-generating diagram tools.

Here's an example:

Image title

Audience: Technical people within the software development team, especially software developers.

Conclusion

Documenting software architecture is a difficult thing to do. There are several ways of going about it and each presents different aspects of the system.

It's always important to keep your audience in mind and not to get bogged down with too many details.

Discover how to optimize your DevOps workflows with our cloud-based automated testing infrastructure, brought to you in partnership with Sauce Labs

Topics:
software architecture ,devops ,communication ,diagrams

Opinions expressed by DZone contributors are their own.

THE DZONE NEWSLETTER

Dev Resources & Solutions Straight to Your Inbox

Thanks for subscribing!

Awesome! Check your inbox to verify your email so you can start receiving the latest in tech news and resources.

X

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}