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.

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.

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.

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:

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:

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.