The best UML. Sequence diagram.
While many UMLs are overkill. There are a few useful ones.
Some of them got killed by the misunderstanding of the agile movement. It often works because most of the features to be implemented are simple. Tech debt gets accumulated, but it still works. However, for more complex solutions fake-agile approach fails. Luckily, conference talks say “enough tech design upfront”, which is an improvement to “no design upfront”.
When building software: user story mapping, event storming, impact mapping, 2x2 matrixes, C4 model (on a 2.5 level), road mapping, and value stream visualisations are extremely useful. So is the Sequence Diagram.
Sequence Diagram
In columns, we put different actors/objects/tech components. Time flies from the top to the bottom. Horizontal arrows explain the communication between the objects.
Imagine a frontend application that needs to compose its layout based on the JSON from the CMS system. The layout might be cached. Then it populates it with the data received from the API Gateway. Behind the gateway are 2 services, which store data being used in a single page on the frontend.
And each technical component is owned by a separate team (let’s skip the divagations on end-to-end stream-aligned teams; we have component teams here).
After seeing a diagram, questions arise:
What’s stopping us from caching the CMS response in that flow? Is there an alternative mechanism for fuelling the cache? So we do not miss the cache when executing the same request again?
What’s the reason for the final request being sent directly to the Pricing Service instead of getting this data in the first request to the API Gateway?
Agile coding is not Engineering
Without a diagram, we would need thousands of telcos to explain the current state and discuss each aspect. Discussing it without seeing a diagram is just a waste of time, and it is error-prone. Implementation without getting a cross-team understanding would fail. One visualisation can save us tens of hours.
Besides the discussions when designing the flow. A diagram might be used to generate a backlog for multiple teams. Each arrow requires implementation. Each activation bar between the arrows requires implementation.
No matter the scale. Between team members communication. Between modules communication. Between teams communication. Between services communication. Between organisations (3rd parties) communication. A sequence diagram helps to sleep at night.