Archyno
PracticePráctica del modelado

Mantener un modelo al día

Los modelos no se pudren porque la gente sea perezosa. Se pudren porque nada en el flujo real de trabajo obliga a nadie a abrirlos.

6 min de lecturaModelling practice3 de 3

01Why models rot

The usual explanation is discipline, and it is wrong. The same engineers who let a model drift for two years keep their test suite green every day, and the difference is not how much they care - it is that a failing test stops the pipeline and a wrong diagram does not stop anything.

Code is surrounded by machinery that forces attention onto it at the moment it changes: a compiler, a test run, a reviewer who has to approve. A model in a wiki has none of that. Nothing in the path from ticket to production ever requires anybody to open the page, so nothing ever surfaces the disagreement. The model does not get worse - the system moves, and the model stays exactly where it was.

02Attach it to something that already happens

Every arrangement that works has the same shape: the model is placed where an existing step will run into it.

Put the view in the repository. A diagram committed as Mermaid beside the code appears in the diff when its file is touched and gets read by whoever reviews the change. It is the only mechanism on this list that costs nothing to sustain, because the review was already happening.

Reference views from decision records. A short architecture decision record that links the view showing the structure it decided means the view gets opened every time somebody asks why the structure is that way - which is precisely when its being wrong would matter.

Make the model the source of a thing people need. If the deployment view generates the diagram in the runbook, or the domain model generates the glossary the support team searches, then somebody notices within days rather than quarters.

Reach for it when

  • A view lives in the repository and changes in the same pull request as the code
  • A decision record links the view that shows what it decided
  • The model generates something a team already relies on
  • One named person owns each view, and the list of views is short enough to name owners for

Reach for something else when

  • A quarterly review nobody has scheduled
  • A wiki page that only the author has ever opened
  • An exported PNG sitting beside the source it was generated from
  • Any arrangement that requires somebody to remember

03Shrink it, and delete the rest

The other half of the answer is that most models are too big to keep, and no process fixes that. If maintaining the model would take a day a month and the team has an hour, the model will go stale regardless of how the review is arranged - so the honest move is to cut it down to the hour.

That is the same test as scoping, applied later: whichever views cannot name a decision are the ones to drop, and dropping them is not a loss because they were not being read. What remains is small enough that its being wrong is noticed.

Then actually delete the rest. This is the step people will not take, and it is the one with the clearest arithmetic. A missing diagram costs a reader ten minutes of asking somebody; a confidently wrong diagram costs them a day and, if they are unlucky, a decision made on it. Documentation you will not maintain is not neutral, it is a trap with your team's logo on it.

In one line each

  1. 01Models rot because nothing in the delivery flow obliges anybody to open them.
  2. 02Attach each view to a step that already happens: a diff, a decision record, a generated artefact.
  3. 03Any process that depends on somebody remembering has already failed.
  4. 04Cut the model to the maintenance budget the team actually has, not the one it should have.
  5. 05Delete what is left, and date what you keep. A wrong diagram costs more than a missing one.

04Preguntas frecuentes

¿Por qué caduca la documentación de arquitectura?

Porque nada en el proceso de entrega obliga a nadie a abrirla. El código tiene pruebas y revisión que fuerzan la atención cuando cambia; un modelo en una wiki no tiene equivalente, así que se desvía en silencio y nadie lo descubre hasta que confía en él y se equivoca.

¿Cómo se mantiene un modelo al día?

Engánchalo a un paso que ya ocurre. Un diagrama en el repositorio aparece en el diff de una pull request; una vista citada por un registro de decisión se abre cuando la decisión se revisa. Cualquier cosa que dependa de una revisión periódica que nadie ha programado no sobrevive al primer trimestre ocupado.

¿Es mejor borrar un diagrama caducado o dejarlo?

Borrarlo. Un diagrama que falta le cuesta al lector diez minutos de preguntar; uno equivocado con seguridad le cuesta un día y una mala decisión. Lo que no vas a mantener es un pasivo y no un activo, y quitarlo es la mejora más barata que existe.

Todos los artículos