I realized the other day that I don't use diagrams while developing software very often and was considering using them more often. Do other people find them useful and how do you use them? Which types of diagrams do you use and how formal are you about using them? (UML, data flow diagrams, sequence diagrams, unstructured flowcharts, etc.)
When I've seen other people's diagrams they can sometimes be incredibly helpful and sometimes be completely unhelpful. I've also heard of strict diagram creation requirements actively hindering projects. If you do use diagrams, how do you use them effectively and avoid problems?
Structured diagrams like ERD and the C4 model help. But I'm not convinced these add much value over the equivalent textual description (I'd rather generate an ERD from SQL; where my SQL is the source of truth). And importantly, they're generally lacking one important dimension: time.
The only diagram I regularly use for software is the Sequence diagram. It has well defined semantics: actors/components across the X axis with their interactions ordered by time down the Y axis. It's a secret weapon for modeling any system that has a distinct "flow" through the steps. You can immediately see not just what components are related to each other, but exactly how they interact over time to produce the end result. It makes it fairly obvious where every bug lives and where every new feature request must be added. It's the only diagram that I cannot replace with prose or a high-level programming language.
And even still, it's worth "writing" your sequence diagrams instead of "drawing" them. Mermaid's sequence diagram markup is lovely and renders directly in GitHub.
One of the few times I've used diagrams were some entity-relationship (ER) diagrams of some databases that were generated by a tool and I found them pretty useful. They helped me get a big picture understanding of the database and see relations much easier. It also helped me notice some small issues with the database that I don't think anybody had noticed like some orphan tables and missing foreign key references. Putting static images in documentation might not be ideal if the database changes quite a bit, but it might also not be the worst if you put the caveat that they might not be up to date. They're easy enough to regenerate when you want an up to date ER diagram of the database.
I've also seen a single incomprehensible diagram used as the only documentation for an entire existing system or a system to be built before which was pretty frustrating. That leads me to think that diagrams should probably aid and be used in addition to other documentation/explanation rather than be the sole explanation.
(solopreneur and someone that works in a 4 people startup)