This article teaches how to visualize the architecture for the high level design (HLD) document, so that software engineers and technical writers can enhance communication.
A HLD document without diagrams is self-sustained but intangible. Humans prefers visualization over text, as the old saying “a picture is worth a thousand words”. To share ideas effectively, you need to visualize the architecture as diagrams.
You can visualize the architecture using the following three principles:
- Make it zoomable.
- Make it clear.
- Make it changeable.
Make it Zoomable
Make the visualization of architecture easy to zoom in and zoom out. The screen has limited space for describing everything in a single diagram. Practically, we create zoomable views for the architecture.
Think of using a map application. You see a country at first. Zoom in, you see cities for a country. Keep zooming in, you see roads and streets. Some map applications offer at-eye-level street views.
Like a map, a zoomable visualization typically involves three types of views:
- Context.
- System.
- Component.
Context
Context view describes the system boundary and the relationship with interacting entities. It helps to display how a system interoperates.
Context view captures the architecture with no interior structure but surrounded with interacting entities, such as personas, other systems, environments. It focus on external factors and helps readers to get the agreement on the scope.
System
System view describes the components of a system and the interactions between those components.
You may draw the component view using sequence diagram, data flow diagram, control flow diagram, networking diagram or deployment diagram whichever suits your need. Sometimes, you need more than one diagrams to describe a system from different perspective.
Component
Component view further breaks down a system component. You can use the same diagram type as used for the system view.
You need to decide whether to include component view in the HLD document. One…