UML in Practice: When a Diagram Helps and When It Does Not

UML discussions often present two extremes: model the system “properly” or use informal boxes and arrows. In delivery work, a diagram’s value comes less from notational purity than from the question it helps a team answer.

What UML contributes

UML is a family of notations for describing system structure and behaviour. It makes an assumption visible by showing participants, components, states, or the order of interactions, allowing the team to check whether it shares the same model.

A diagram does not replace requirements, code, an API contract, or an architecture decision. It brings the relevant parts into one view. If a discussion changes the decision, a temporary diagram has already done useful work even when it never becomes permanent documentation.

Start with the question

Question	Suitable diagram
Who interacts with the system, and why?	Use Case
In which order do participants exchange messages?	Sequence
What are the major parts of the solution?	Component or Package
Which states can an object move through?	State Machine
How does a process or algorithm branch?	Activity
Which entities and relationships matter in the domain?	Class or a related domain model
On which nodes and execution environments are artefacts deployed?	Deployment

Not every question needs formal UML. A team may choose C4 for system context, BPMN for a business process, an ER model for data, OpenAPI for an interface, or a plain sketch for a quick conversation.

The notation is useful when the main audience can read it and it preserves the relevant meaning. A formally correct model that nobody understands has failed as communication.

Where UML tends to help

Non-trivial interactions. A sequence diagram can expose retries, timeouts, asynchronous responses, and several participants without a long narrative.

Lifecycles. A state machine helps when not every transition is legal or status controls rights and actions.

Ownership boundaries. A component diagram can show which part owns a rule or dataset and where a contract crosses team boundaries.

Handover and onboarding. A small set of current views gives a newcomer a starting point before they assemble the picture from code, documents, and conversations.

Option analysis. A draft model allows the team to compare approaches while change is still relatively cheap.

When a model becomes a burden

Describing an entire system at one level of detail usually creates more maintenance than value. Frequently changing internal classes age faster than stable contracts and component boundaries.

Another warning sign is drawing the model after the decision solely to satisfy a required artefact. That diagram records compliance rather than supporting thought and is often the first documentation to become stale.

UML may be unnecessary when:

• text or a table answers the question more clearly;
• the view duplicates generated documentation;
• the audience already uses another stable notation;
• nobody owns updates;
• changing the diagram affects neither decisions nor support.

Choosing the right depth

Before modelling, I ask five questions:

1. Which decision should this view support?
2. Who will read it?
3. Which detail can change the decision?
4. How long must the model remain current?
5. Who will update it when the system changes?

A meeting may need only a draft. A cross-team contract needs agreed terminology and a version. Operational documentation needs a clear connection to the deployed environment and an owner.

Keep documentation close to change

A model is easier to maintain when it lives near the code or document that changes with it. Text formats such as PlantUML or Mermaid make review and version history convenient, but they are not mandatory. A visual editor is better when the team genuinely uses it.

The important part is checking the view in the same process that changes the decision. A separate annual “diagram audit” rarely keeps pace with delivery.

UML is not a silver bullet and should not be a test of whether an analyst is a real professional. It is one way to reduce ambiguity. Model the part of the system where a shared visual view reduces decision risk more than it costs to create and maintain.

PlantUML and Mermaid are diagram-authoring tools, not the UML specification; check the notation each supports. A deployment node can represent a device or an execution environment. Data ownership and SLOs need explicit annotations and team agreements: the diagram type does not establish them.

Notation and semantics are defined in the OMG UML specification.

One request, two different questions

Suppose a user submits a request and a staff member handles it. For allowed transitions, start with a state model:

State	Permitted action	Next state
Draft	Submit after required-field validation	Submitted
Submitted	Authorised staff member takes ownership	In progress
In progress	Record the outcome	Completed
Completed	Read the outcome	Completed

Can it be cancelled, returned for clarification or reopened? Agree on those rules rather than inventing them while drawing.

For a lost server response, the state table is insufficient. Examine the sequence: client submits, server persists, response is lost, client retries with the same key. A sequence diagram should expose the retry and persistence boundary, not just an arrow along the happy path.

The same feature needs different views for different questions. If a small table resolves the issue, a formal diagram may add nothing.

---

Originally published on my Telegram channel @it_underside.

Yours, DPUPP