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 aroun…
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.