Over a million developers have joined DZone.

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

The DevOps Zone is brought to you in partnership with Sonatype Nexus. The Nexus Suite helps scale your DevOps delivery with continuous component intelligence integrated into development tools, including Eclipse, IntelliJ, Jenkins, Bamboo, SonarQube and more. Schedule a demo today

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.

The DevOps Zone is brought to you in partnership with Sonatype Nexus. Use the Nexus Suite to automate your software supply chain and ensure you're using the highest quality open source components at every step of the development lifecycle. Get Nexus today

Topics:
software architecture ,devops ,communication ,diagrams

Opinions expressed by DZone contributors are their own.

The best of DZone straight to your inbox.

SEE AN EXAMPLE
Please provide a valid email address.

Thanks for subscribing!

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

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

{{ parent.tldr }}

{{ parent.urlSource.name }}