The Art of Crafting Architectural Diagrams. Guidelines

In our first article we looked at how we can identify some of the challenges that arise when creating architectural diagrams — from color to mixing runtime and static elements to diagrams that might be too cluttered. Now let’s look at the guidelines we need to have in mind.

Guidelines to follow when creating architectural diagrams

Apart the above pitfalls, which must be part of a prerequisite checklist in order to avoid them, there are also general guidelines on how to properly create diagrams:

Choose the optimal number of diagrams

• As Philippe Kruchten said, “architecture is a complex beast. Using a single blueprint to represent architecture results in an unintelligible semantic mess.” To document modern systems we cannot end up with only one sort of diagram, but when creating architectural diagrams it is not always straightforward what diagrams to choose and how many of them to create. There are multiple factors to take into consideration before making a decision; for example, the nature and the complexity of the architecture, the skills and experience of the software architect, time available, amount of work needed to maintain them, and what makes sense or is useful for meeting stakeholders concerns. For example, a network engineer will probably want to see an explicit network model including hosts, communication ports and protocols; a database administrator is concerned about how the system manipulates, manages and distributes the data, etc. Based on all of these aspects, it is recommended to pick up the optimal number of diagrams, whatever that number is.
• If there are insufficient diagrams (e.g. under-documenting), parts of the architecture might be hidden or undocumented; on the other hand, if there are too many (e.g. over-documenting), the effort needed to keep them consistent, updated and not fragmented might considerably increase.

Keep structural and semantical consistency across diagrams

• Every diagram should be consistent with the others in terms of boxes, shapes, borders, lines, colors, etc. The structural look and feel should be the same and every stakeholder should have no difficulties in understanding diagrams created by different developers inside a team. Ideally, stick to a common diagramming tool and reuse it across all projects.
• From the semantical point of view, all of these diagrams should be periodically synchronized to latest code changes and between them, since a change in one diagram might impact others. This process might be manually or automatically triggered by using a modeling tool. The latter is the preferred mechanism but this depends from project to project, in all cases the idea is to maintain consistency between diagrams and code, independent of the method or tool. Simon Brown said “diagrams are not useful for architectural improvement if they are not connected to the code”, which emphasizes the idea of semantical consistency.

Find out more at — http://bit.ly/2DXVSwo

Originally published at www.luxoft-training.com.