Cuánto de un sistema modelar
La única pregunta que lo resuelve es qué decisión debe informar el modelo, y la mayor parte de lo que la gente modela no informa ninguna.
6 min de lecturaModelling practice1 de 3
01The test: name the decision
Before drawing any view, finish this sentence: "This view exists so that [person] can decide [thing]." If you cannot fill in both blanks, do not draw it.
The test works because it is falsifiable, which is what every other piece of advice on this subject is not. "Model the important parts" cannot lose an argument; "this class diagram exists so the platform team can decide whether billing owns the tax calculation" either is true or is not, and the person named can be asked.
Applied honestly it removes most of what gets modelled. A diagram of the current system drawn because somebody should document it informs nothing. A view showing every service in the estate informs nothing, because no decision is about all of them at once. What survives is a small number of views, each aimed at an argument somebody is having.
02Three ways an unscoped model fails
It becomes a second implementation. Every class, every field, every call - a model at that fidelity is a copy of the codebase written in a notation, and the copy is always the one that is wrong. This is the failure that gives modelling its reputation, and it comes entirely from not asking what the model is for.
It becomes a picture of the org chart. Unscoped models drift towards showing every team's system at equal weight, because that is politically the easiest arrangement. The result is a diagram in which the two components that actually interact are the same size as twenty that do not, and nobody can find the question.
It becomes unmaintainable in the ordinary way. Not dramatically - simply by containing more detail than the team has appetite to update, so a few elements go stale, then a few more, and within two quarters the model is a thing people check against the code rather than trust.
Reach for it when
- A decision is genuinely open and two people disagree about it
- A change will cross several teams and somebody has to see the seams
- A future reader will need to know why a non-obvious structure exists
- A new joiner needs the shape of the domain, not the shape of the code
Reach for something else when
- Documenting a system that nobody is about to change
- Recording a decision already made and already obvious from the code
- Modelling because a template or a process asks for a diagram
- Any level of detail the team will not maintain after the project ends
03Working at the right size
One model, several small views. Scope is a property of the view rather than of the model - the model can hold everything anybody has entered, and each view shows the handful of elements one decision needs. That distinction is what ArchiMate's viewpoint mechanism is for, and it applies just as well to UML.
Model one level below the decision, not two. If the argument is about which service owns a responsibility, model the services and their dependencies. Do not model the classes inside them; that detail cannot change the answer, and it is the detail that will rot.
Delete views that have served their purpose. A view drawn for a migration that happened is finished, and keeping it means a future reader will find a confident diagram of an architecture that no longer exists. Deleting documentation feels wrong and is usually right.
In one line each
- 01Every view must name a person and a decision. If you cannot, do not draw it.
- 02A complete model of an unbuilt system is confident guessing, and it hardens the guesses.
- 03Model one level below the decision. Detail that cannot change the answer will rot.
- 04Scope belongs to the view, not the model - one model, many small views.
- 05Delete a view once its decision is made. A stale diagram is worse than none.
Next in this series: naming conventions, and then keeping a model current.
04Preguntas frecuentes
¿Cuánto de un sistema debería modelar?
Lo que informe una decisión que alguien vaya a tomar de verdad. Para cada vista que vayas a dibujar, nombra la decisión que sostiene y la persona que la toma; si no puedes nombrar ambas, la vista documenta un sistema en lugar de ayudar a cambiarlo, y nadie la va a leer.
¿Debo modelar el sistema entero antes de empezar?
No. Un modelo completo de un sistema que nadie ha construido es un conjunto de suposiciones dibujadas con seguridad, y su efecto principal es hacer esas suposiciones más difíciles de abandonar. Modela la parte donde la decisión está realmente abierta, construye, y modela la siguiente cuando llegue la siguiente decisión.
¿Cómo sé que un modelo tiene demasiado detalle?
Cuando un cambio en el código obligaría a cambiar el modelo y nadie lo hace. Ese es el punto en el que el modelo tiene más detalle del que el equipo puede mantener, y a partir de ahí cada diagrama se aleja del sistema mientras sigue pareciendo autoritativo.
Lecturas relacionadas