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.
I have been trying to enforce this concept inside of my current organization. There is the saying that a picture is worth 1,000 words. I would extend that, suggesting that a diagram is worth well over 10,000 words.
As an example, we had a project at work that kept getting thrown on my desk and every time it showed back up I would respond back with 20 questions based on limited writeups and JIRA tickets. Each time it would come back, I would get more confused, my team got confused, the architect was confused. Everyone was on different pages.
Then finally, we brought a new technical project manager onto the project (at my bequest to the CTO) and within a week that TPM created a diagram, we have one 30-min meeting where he presented the diagram. We then realized that each team was on completely different pages with what needed to be built. Everyone asked a few questions, but there were far fewer questions than earlier because many of the questions were answered by the diagram. We then built out the solution 3 weeks later.
So we spent 10 weeks spinning our wheels, building, unbuilding, rebuilding, and being confused as we all tried to get in alignment. THen one diagram and a 30 minute meeting later and we all left understanding exactly what we needed to do, we were all in alignment on the project and we were confident in what we needed. It also helped us call out things gaps in the initial solution, which we probably never would have identified until we ran into the problems when following the earlier method.
One diagram can save HOURS (even tens of hours) of time for everybody. It reduces errors and misconfiguration and aligns teams. Diagrams are your best friend. No matter how simple something is, I always make a diagram.
Good point. Finding a middle ground is the way to go. Keeping enough details in the diagrams to keep them useful but without the extra overhead. You cant keep all the details in the diagrams, they belong in the code.
Often, someone will be explaining something to me, but it's too complex to mentally model, or I'm not familiar enough with the architecture they're describing. So I'll say "I need boxes and arrows", we'll step over to a whiteboard, and it will be cleared up in a few minutes.
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.