You can use UML models to capture and evolve a software system's system gist separately from the user-interface and technology choices that change around it; this page is for anyone deciding how to preserve and execute that description over time.
Keep the system description separate
A software system has a unique purpose: the information it handles, the rules it follows, and the actions that create value. This page calls that purpose the system gist.
The system gist is not the same thing as the technology used to deliver the system. A web framework, a desktop client, a database library, and a visual style can all change without changing the business problem the system solves.
For example, consider a system for handling customer orders:
- The concepts Customer, Order, and Order line belong to the system gist.
- The rule that an order has one customer and can contain many order lines belongs to the system gist.
- Whether users work with the order through a desktop application or a web application is an implementation choice.
- The visual appearance and interaction patterns chosen to meet current user expectations are also separate from the order model.
Use UML class diagrams to describe the information and relationships in examples such as this one. Start with information design when you need to identify the important information in the business domain.
Why prose and code are not enough
Prose requirements can describe a system, but prose leaves room for multiple interpretations. It is also difficult to verify: prose cannot be compiled, type-checked, or executed.
Source code can be compiled and tested, but it combines several concerns in one representation. Code often contains both the domain rules and the choices of a particular implementation technology. It can therefore be difficult for stakeholders and new team members to identify the intended system gist.
A model gives the team another representation: a structured, machine-readable description that is easier to discuss than implementation code and more precise than prose. The model is where you can review, criticize, and evolve the system description before it becomes dependent on a specific delivery approach.
For a discussion of what happens when the system gist is not explicitly modeled, see Training:What if UML was forbidden.
Use UML to describe the gist
UML (Unified Modeling Language) is a language for describing a system in a structured form. In this context, use it to express domain concepts and their rules rather than the details of a particular user-interface framework.
A UML model can include:
- Classes, attributes, and associations that describe the information in the domain.
- Cardinality rules that state how many objects may participate in an association.
- Generalization and specialization, where a subclass adds detail to a superclass. See UML inheritance.
- Association classes when the relationship itself needs information. See Training:Association classes.
- State machines when an object has defined states and transitions. See UML state machines.
The model must have a purpose. It is a simplified representation of real-world concepts, so its value comes from whether it supports the decisions and behavior the system requires. For an introduction to the language, see Documentation:What is UML.
Distinguish gist, modernity, and fashion
When you discuss a design decision, classify it before deciding how to handle it.
| Area | Meaning | Order-system example | How to decide |
|---|---|---|---|
| System gist | The ideas and actions that produce value in the domain. | An order must belong to a customer; an order contains order lines. | Research the domain and agree on the business facts and rules. |
| Modernity | Current ways of solving known technical problems. | Choosing a delivery technology for entering and viewing orders. | Evaluate technical practices, tools, and the expected value and pace of change. |
| Fashion | Choices driven primarily by current expectations and preference. | The visual style and interaction patterns used in the order screen. | Let users, stakeholders, or the market guide the choice when facts do not settle it. |
These areas change at different speeds. The system gist evolves with the business. Modernity changes as technical approaches change. Fashion changes with user and market expectations. Do not treat a replacement of delivery technology as a reason to rewrite the business model.
Praise to UML explains this distinction in more detail and why it matters to software development.
Execute the model
Model-driven development means developing the system gist in a machine-readable model and using software that turns that model into an executable system. A model executor is the software that brings the model to life in a particular environment.
In MDriven, the model is not only documentation. It can be compiled and executed. This enables a workflow in which the model remains the home of the domain description while the executor addresses the selected implementation environment.
The separation has a practical effect:
- Model the order domain: Customer, Order, and Order line, including their attributes, associations, and rules.
- Discuss and refine that model with the people who understand the business.
- Execute the model using the chosen MDriven implementation approach.
- When delivery requirements change, keep the domain model as the starting point and change the execution approach rather than recapturing the system gist in a new technology-specific codebase.
The page's historical examples describe models executed through Delphi, Windows Forms, ASP.NET, Silverlight, WPF, and C# MVC5. The point is not that one delivery technology is permanent. The point is that a well-maintained model can outlive individual implementation approaches.
Treat the model as a long-lived asset
Keeping the system gist explicit gives both developers and decision-makers something they can inspect and discuss. It reduces reliance on undocumented assumptions in code or on the collective memory of a team.
This does not remove the need to make implementation decisions. It makes those decisions clearer: preserve and evolve the domain model because the business changes; replace or adapt the executor when technical or market requirements change.