Ask HN: Do you use diagrams while developing software?
4 comments
The problem with most diagrams is that they lack semantics. What do the boxes and arrows really mean? As soon as you start getting fuzzy, the diagram is effectively useless. If you're up for a laugh, try to play "Diagram Bingo" next time you encounter one: https://c4model.com/bingo/
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.
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.
I'll add a couple of my own thoughts here as well.
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.
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.
Very rough pen and paper draft very rarely. Never for other people.
(solopreneur and someone that works in a 4 people startup)
(solopreneur and someone that works in a 4 people startup)
I have an app that is growing a little complex, and today I am actually working on graphing the routes and the relations between those pages (breadcrumbs/XHR/redirects/links). It's actually really painful. I'm doing it with Graphviz.
I’m the creator of flowchart.fun which is a quick text-to-diagram tool. If I’m being honest I didn’t use it much when developing stuff at first but of late I find it’s really nice if I have a mental dependency graph that I just want to visualize to help prioritize tasks and think about blockers. Mermaid.live is awesome for this. Anything you can drop into quickly imo
The painful part is mostly collecting the data, inputting it into DOT is not too bad. The result is quickly turning into a hairball though.
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?