There's some discussion here about linking diagrams to code or vice-versa. And while that's useful for documenting code already written, where I personally have found diagrams to be the most useful is in the planning discussions before and during writing the code in the first place.
A room full of people can talk about things for hours without making progress, but as soon as you starting moving boxes and arrows around on a screen suddenly people have more targeted thoughts about what they agree with or what should change.
The diagram is useful for planning the extend and structure of the work to be done, and coordinating the team that is building it to make sure we have a shared mental model.
Once that project is done, the diagram is likely already out of date. No plan survives contact with the enemy and all that. But for this use case its job is complete and it can be discarded or archived with the rest of the planning work.
Diagramming for long term documentation is a slightly different use case, and for that I tend to agree more with documentation that at least lives with the code and can be updated alongside it, manually or automatically. I just personally haven't worked in orgs large enough to pay off that level of investment.
A room full of people can talk about things for hours without making progress, but as soon as you starting moving boxes and arrows around on a screen suddenly people have more targeted thoughts about what they agree with or what should change.
The diagram is useful for planning the extend and structure of the work to be done, and coordinating the team that is building it to make sure we have a shared mental model.
Once that project is done, the diagram is likely already out of date. No plan survives contact with the enemy and all that. But for this use case its job is complete and it can be discarded or archived with the rest of the planning work.
Diagramming for long term documentation is a slightly different use case, and for that I tend to agree more with documentation that at least lives with the code and can be updated alongside it, manually or automatically. I just personally haven't worked in orgs large enough to pay off that level of investment.