You can use this thought experiment to identify where your software system's essential knowledge lives when you do not maintain a UML model; it is for developers, architects, and decision-makers responsible for evolving a system over time.
Imagine UML was forbidden
Imagine that UML, or any other structured way to describe a system, was forbidden. The system would still have a system gist: the ideas, information, and rules that combine to produce value.
The gist does not disappear because it is not modeled. A running system is an implementation of that gist, regardless of whether the original ideas were captured in a diagram, prose, discussions, or directly in code.
The question is not whether the gist exists. The question is whether people can find it, discuss it, verify it, and change it without depending on individual memory or implementation details.
Separate system gist from modernity and fashion
System gist, modernity, and fashion change for different reasons:
| Area | Meaning | Example in a customer-order system |
|---|---|---|
| System gist | The domain ideas and rules that make the system valuable. | A customer places orders; an order contains order lines; each order line refers to a product. |
| Modernity | The current technical ways of implementing known problems. | Whether the system uses a particular user-interface framework, database technology, or deployment approach. |
| Fashion | Choices driven primarily by what users or the market currently expect or prefer. | The visual style, interaction patterns, and terminology that make an application feel current. |
If UML is not used, these concerns tend to become entangled in source code. A developer trying to understand whether an order may be cancelled then has to read code written in a particular framework and style. The business rule is mixed with technical choices that may have changed since the rule was introduced.
Where does the gist go?
Without a maintained model, the system gist usually ends up in one or more of these places.
Source code
Source code can be compiled, type-checked, executed, and tested. These properties make it essential for implementation. However, code is also an interpretation of a requirement, expressed through the tools, libraries, architecture, and style chosen at a particular time.
For example, the rule "an order must have at least one order line before it can be submitted" may be spread across a user interface, a service, a database constraint, and tests. A developer can eventually discover the rule, but must first separate it from the implementation mechanics.
Code therefore reveals what the system currently does, but it does not automatically provide a clear, domain-level description of what the system is meant to do or why.
Prose documents
Requirements documents, scenario descriptions, and other prose may describe the system gist. Prose is useful for explaining goals and context, but it is open to interpretation and difficult to verify in the same way as executable code.
Consider the sentence: "Customers can change an order before processing." It leaves important questions unanswered:
- What does "processing" mean?
- Can a customer add and remove order lines, or only change quantities?
- Is an order change allowed after payment?
- Who decides whether processing has started?
A prose document can contain incomplete or outdated statements without producing a compilation error. When developers suspect that documentation is not current, they stop relying on it and return to the code. Documentation then becomes something maintained to provide reassurance rather than something used to guide decisions.
Team memory
Another common approach is to invest in experienced developers and let the team's shared understanding carry the system gist. Skilled and motivated developers are essential, but collective memory is not a durable system description.
In the order example, one developer may know that an order cannot be cancelled after warehouse picking begins. If that knowledge exists only in that developer's memory, a manager cannot easily assess the impact of a new cancellation policy, and a new team member cannot independently check the rule.
This creates a gap between the people who know the system and the people who must make investment and priority decisions. Developers are left to decide how much effort goes into preserving the gist, adopting current technology, or following current fashion. Management then lacks a clear basis for understanding or trusting those priorities.
The cost of letting code speak alone
When code is the only reliable representation of the system, understanding depends on reading implementation details. That makes the system harder to discuss with stakeholders, harder to transfer to new team members, and harder to evolve deliberately.
The result is not that developers are incapable of maintaining the system. The result is that ownership and control of the system gist are weakened. The organization depends on particular people and on a particular implementation to answer domain questions.
This risk is especially visible when technology changes. A user interface or delivery mechanism may need replacement because modernity has moved on. If the domain ideas are only present in code, replacing the technical solution can require rediscovering the system gist at the same time.
A practical test
Ask the following questions about one important business rule:
- Can a developer, domain expert, and decision-maker find the rule without reading implementation code?
- Can they agree what information the rule concerns and what relationships apply?
- Can they identify the effect of changing the rule before changing the implementation?
- Can a new team member learn the rule without relying on one long-serving colleague?
If the answer is no, the system gist is likely held mainly in code, prose, or team memory.
For information-focused systems, start by identifying the concepts the business deals with and the relationships between them. For example, identify Customer, Order, OrderLine, and Product, then state which attributes and associations are required. Information design explains why following the information helps reveal the business. UML class diagrams provide a structured way to express those concepts, attributes, associations, and cardinalities.
The point of the thought experiment
UML need not literally be forbidden for these problems to occur. The same effect appears whenever a structured model of the system gist is absent or ignored.
The purpose of modeling is not to replace code, prose, domain expertise, or discussion. It is to give the system gist a representation that is easier to inspect than implementation code and less ambiguous than prose alone. The model can become the place where people understand, criticize, and evolve the domain before it takes the expensive form of implementation code.
The next chapter describes this missing link: using models to keep the system gist separate from changing implementation choices.