HN Explorer

Ask HN: What diagrams do you use in software development?

241 points by cies ↗ HN
There's currently an article on the front page about the death of UML[2]. While UML's inheritance diagrams have been dead to me for a long time, I still like the sequence diagrams.

Besides that I sometimes still draw ERDs and I love JJG's Visual Vocabulary[1] for drawing "interaction diagrams".

What types of diagrams do you use with your team?

[1]: http://jjg.net/ia/visvocab [2]: https://news.ycombinator.com/item?id=26934577

156 comments

[ 2.9 ms ] story [ 222 ms ] thread
sidcool
C4 model helps for existing architectures. I use Mural for that.
cies
Did not know of this, thanks for mentioning. I think this can help me to make my architecture diagram less loosely defined.
cies
To answer my own question (I forgot to mention some):

* ERDs

* UMLs sequence diagram

* State diagrams

* JJG's VisVocab (for diagramming interaction, i.e.: screens and actions): http://jjg.net/ia/visvocab

* And some (not well defined) type of architecture diagrams

* Sometimes a branching diagram to explain a hairy git branching issue to a co-worker

tomerv
The C4 Model looks pretty good, it's like a very simplified UML. The main selling point for me is that it's very intuitive to understand without knowing anything about it in advance. However, I don't have much actual experience with it so far, so I'm still not certain it's the best solution.

https://c4model.com/

linkdd
This.

The main selling point for me was the "zoom in/out" aspect. Instead of having a HUGE UML diagram, you have a bunch of small diagrams, each focused on a single part of the described system and the interactions between its components.

marton78
I second the C4 model, its concept of different zoom levels is great! It guides thinking when specifying an architecture, and is a great didactic device when explaining said architecture to executives / investors.
smoe
I found the first 2 levels of c4 very useful to get a quick sense what the system consists of, what it interacts with and who the users are. Also because it is something non-tech people can understand and reason about.

But for level 3, 4 it gets tedious to do the diagrams at time and harder to keep them updated over time. Personally I prefer to just read the code and only have diagrams in special cases at this point

jasonpeacock
C4 Model + PlantUML is the the best combination.

You can version your diagrams with your code (or in their own repo) using PlantUML, and by following the C4 Model you create digestible diagrams that are easy to understand.

victor96
I also love the simplicity and structure of the C4 model. I'm currently working on a tool at http://icepanel.io which implements the concepts that are talked about.
buro9
* Sequence https://plantuml.com/sequence-diagram

* Use case https://plantuml.com/use-case-diagram

* Object https://plantuml.com/object-diagram

* Activity https://plantuml.com/activity-diagram-legacy

* State https://plantuml.com/state-diagram

Sequence and Activity are my most used - beyond the ones above logical architecture tends to be a Draw.io created abstraction that ends up in a Google Doc... stuff like this: https://camo.githubusercontent.com/f14ac82eda765733a5f2b5200... (not one of mine)

p_l
Similar for me, UML2.0 diagrams done using PlantUML. If I had the option, I'd use Enterprise Architect, but it's way too expensive to justify - the benefit would be that it keeps a separate store of "objects" involved in the project which you can refer to from your diagrams.
etripe
Having used both, Enterprise Architect might be more formally maintainable, but from a CBA (can't be arsed) perspective, PlantUML blows it out of the water. If you use imports in PlantUML, you can define your "objects" or even common actors or events in their own separate pumls, anyway.

Just my 100% subjective read.

p_l
from what I've seen of an architect working in EA on video call, EA allows to more flexibly define objects - and doesn't put any preconceptions on their use. With PlantUML I'd beware that my common definitions have assumptions about being used in specific contexts.

But it's something to test out! :)

TeMPOraL
Definitely worth checking out :). At some point, they bit the bullet and included a programming language inside[0].

https://plantuml.com/preprocessing

It's enough to make it easy to organize common chart elements into libraries, and even create some DSL here and there - the latter being helpful if you're using PlantUML for note taking or in lieu of doodling :).

For instance, I got a very good mileage out of "trivial" definitions like:

  !procedure call($source, $target, $call)
  $source -> $target: $call
  activate $target
  !endprocedure
Forming a mini-DSL that let me turn notes like:

  call("Someone", "SomeoneElse", "FooBar()")
  asynccall("SomeoneElse", "SomeService", "Run(a=42)")
Into a rather large sequence diagram that's also readable as text, and possible to auto-generate to some extent.

--

[0] - Which looks like a spawn of an unholy marriage between PHP and C preprocessor... but hey, it's a programming language.

deanclatworthy
After spending so much time messing around in draw.io and other crappy tools, I also settled on using PlantUML recently. Easy to commit to VCS, and can easily be shared.
tnzm
+1 for PlantUML. Mostly the Sequence diagrams - everything else quickly becomes a mess unless you take extra pains to prevent arrows from turning into a tangled bundle.

I don't care about the UML vocabulary, just give me boxes and arrows and labels and a way to draw them semantically instead of some overengineered point-and-grunt GUI.

Now, if anyone came up with a tool that checked that the code and diagrams match (no code generation please, the code is the source of truth!), now THAT would be lovely.

Just a CLI tool that can be run as part of a CI pipeline, which parses the code into an AST, and checks if entity A still has properties A.B and A.C, and methods A.D and A.E, and that A.D still contains a call to function F - and colors the arrows BRIGHT RED if there's a mismatch. That would be enough for committing a mental map of a codebase to documentation.

billfruit
PlantUML is great but it renders Statecharts in a non-obvious manner.
flower-giraffe
draw.io with embedded plantuml saved as pdf with editable source embedded is a fantastic free alternative to Visio.

Plantuml is excellent for some use cases, but not all.

They use kroki to enable embedded plantuml diagrams, you can save the whole thing as PDF than includes the source and can be edited in draw.io

ghosty141
I only used the Sequence diagrams because they are super useful and the syntax is very intuitive. PlantUML is great
TeMPOraL
Yup, mostly the same set of PlantUML diagrams for me, plus:

* Timing https://plantuml.com/timing-diagram - used it once or twice.

I mostly use PlantUML for myself, in lieu of drawing diagrams by hand (or pointing device).

My main use cases are a) when I'm toying with some higher-level design in my head and want to "see it" in picture form, and b) when making notes about the structure of code as I explore gnarly areas of a legacy codebase.

In that latter case, I've discovered that my "PlantUML notes" follow the code structure close enough that I should be able to coax my editor into generating these for me, semi-interactively. I might get around to doing that at some point.

Quite honestly, I'm surprised I haven't seen anyone doing a generalized "Language Server -> PlantUML" tool for asking questions about the codebase and getting responses in graphical form. As I mentioned yesterday[0], I find myself in need of being able to answer questions like "How does the code get from here to there?", and at least some language servers should have enough information to be able to give that answer[1].

That time when I spent a whole day building a sequence diagram by hand, to document how a certain subsystem is created and used in the very heart of the application, paid for itself very quickly - but I'd much prefer if it was a matter of couple minutes of tuning an invocation like:

  querypuml --type=fromto --from=Foo.cpp:123 --to=Bar.cpp:456 \
            --omit"::utils::*" --omit "SomeClass" \
            --omit-files "module/irrelevant/*"
            -o journey.puml
It would make it much easier to refresh the diagram the next time I need it for reference.

--

[0] - https://news.ycombinator.com/item?id=26937454

[1] - If a language server supports identifying function calls and "jump to definition" (xref), it already has a lazy graph of the code structure, so it's a matter of running a path finding algorithm on it. Of course this can never be perfect (see also: halting problem), but I think a minimum-effort solution would cover 80% of cases, and most of the rest could be covered if attached to a debugger that records traces.

xupybd
Flow charts are huge for me. It's a good way to show a non programmer my understanding of a process they have explained. It also helps me code a little clearer when the business logic is less intuitive.

Also truth tables if I have to work with booleans in excel.

Nursie
Sequence diagrams are about the only thing for a long time.

Otherwise nothing much... random visio-ish things made in draw.io or sometimes scribbled out on the fly during presentations using a wacom tablet. I tend to prefer words, code snippets and config to explain my stuff these days.

laci27
https://draw.io But dbdiagram.io looks amazingly easy to use. And so are the rest of the suggestions. I also realize that I don't use UML with draw.io:)
splittingTimes
Mental model often formed much more around what kind of data flows and interactions happen between components.

As a big fan of Domain Driven Design I found "domain storytelling" a useful technique when adapted to software systems.

With these diagrams it was much easier to convey complex systems and their temporal couplings. Especially to higher Management as they can actually "read" how the sequence of events flow.

Try it out and see if it can be another tool on your belt.

===

https://domainstorytelling.org

pjmlp
UML and Entity Relationship ones.
marvinblum
I use ER diagrams to model data structures, even if they are not stored in a database. I find them to be much clearer than class diagrams for example, and they help to keep an overview of everything. Otherwise, I sometimes use activity diagrams to model some complicated logic but don't use anything else of UML.
rwoerz
UML component, deployment, state chart, class, use case and activity diagrams. I mostly use PlantUML, which is, due to its textual source notation, embeddable into Markdown or AsciiDoc files and are therefore comparably easy to version.

PlantUML works best with sequence diagrams because automatic layout is much easier ("sequential") for them.

pydry
Hand drawn. I like the idea of building diagrams I just tend to find that:

* It's a lot of work to make them look right.

* They become outdated SO quickly. They're dangerously misleading as often as they're useful.

* Lots of people like to create diagrams, nobody likes to maintain.

Hand drawn dated diagrams have a sort of built in advantage that people will assume that it's not been kept up to date, especially if it's scruffy. Also they're quick.

I like the idea of generated diagrams better than drawn diagrams but unfortunately the software just isn't there yet.

Even when you can do it, they usually look shit because the program won't layout nearly (e.g. E/R) and you can't integrate changes to the source (e.g. tables) to annotations/tweaks.

jiehong
But hand drawn diagrams are invisible to people with visual deficiencies.

Usually, plantuml source is more readable, and it’s just almost like writing a list so it’s not too much work.

pydry
I don't find plantuml at all readable as a DSL.

I like the idea of some sort of textual dsl that generates diagrams just not that one and ideally not a UML focused one.

Veuxdo
Have you looked at Ilograph? Its DSL is much nicer than PlantUML and isn't UML-focused.
globular-toast
The topic is about diagrams, though. The point is using visual aids to help with development so that implies being able to see stuff. If I had a visually impaired developer on my team then of course I would make other provisions, but I would still draw diagrams for myself and other members.
grammarnazzzi
> it’s just almost like writing a list so it’s not too much work.

But written lists are worthless to people who are illiterate

globular-toast
Agreed! Hand drawn is quicker, way more flexible, and everyone knows how to do it.

It has a built in version control system: get a new piece of paper and keep the old one.

There is immense power in "reciting" the diagram in front of someone on a new piece of paper or whiteboard. It's essentially adding a whole new dimension to your diagram, as well as space for discussion and interaction along the way. I've not seen someone pull this off well in any electronic format.

Spending time refining diagrams is what you do when you're writing a thesis or book. You have to be very careful when designing your diagrams this way. But it's a complete waste of time when the diagram is for software under development. Those diagrams can and will become outdated very quickly.

montroser
Hand drawn diagrams often have a clarity still elusive in diagramming software.

But we have found that working together in real time -- making a diagram together -- is an incredibly efficient way to strategize about how to solve whatever problem at hand, and then come away with a shared understanding so we can work together on the execution.

We use Plectica[1]. Another popular one is Miro[2].

[1]: https://beta.plectica.com

[2]: https://miro.com

Pinus
Lately I have been wondering whether a "fear" (for want of a better word) of hand-drawn diagrams are causing diagrams in general to be under-used. We're used to having everything typed, TeX:ed, machine drawn, perfect, and we want our diagrams to look like that, too, but using drawing software is hard and time consuming, so we don't diagram at all. But we could just whip out pencil and paper! You don't have to be an artist to draw some boxes and arrows. And the problem of archiving and revision control is solved now that everyone has a digital camera in their pocket (and a JPEG file of an A4/letter page isn't very big by today's standards).
beaconstudios
The best planning experiences I've had in a team were when everything was done on a whiteboard and photographed for posterity. Architecture planning, kanban board, UI mockups, everything - it was a joy not having to wrestle opinionated tools into doing what we wanted.
benhurmarcel
Since I have a tablet and stylus I started sending/showing a lot more diagrams. It's easier to share and looks cleaner than a photo of a paper.
withinboredom
I use Microsoft research’s Lens. It’s amazing for taking pics of whiteboards and drawings and making it look much better than a photo of paper.
bostonsre
Yea, I like the idea of having freely draw diagrams where you aren't constrained to a certain syntax. I used to only do hand drawn diagrams until we started using miro at my company. It's really intuitive and the simplicity and the control just make it so much faster and easier to generate and maintain diagrams. It's been great for design and has been useful for debugging issues in unfamiliar architecture.
billfruit
Some of the diagrams are not viable to draw by hand. Statecharts for eg, derives much of their expressivity from the ability to nest them without limit. Such nested Statecharts require a system which can collapse/expand nested levels, and hand drawn diagrams cannot do that.
alfiedotwtf
Control Flow diagrams to work out logic, turn that into pseudocode in comments, then start implementing under each comment.

Also, ER diagrams because it's easy to translate drawing to normal form

andyjohnson0
The only uml diagram I've really used in the last decade or so is the sequence diagram - for describing use cases for network message exchanges. And even that is in powerpoints and on whiteboards. I can't imagine ever formally documenting anything that way. Too bulky.

I try to avoid over-use of inheritance, so class diagrams don't get used for that. Mostly I use unstructured boxes and arrows for entity-relations, and don't worry too much about notational rigour.

cies
And beyond the UML diagram family? ERDs maybe?
tluyben2
I like bpmn workflows. Especially with the Camunda editor. Not for execution, but for quickly drawing up logic and flows to explain how I suggest we do things. Those diagrams are complete enough to encompass everything: low-level logic to high level cloud and system architecture.

And everyone understands them without any help or explanation.

Molomby
If you have complex interactions sequence diagrams can be a hugely helpful communication tool. I use https://sequencediagram.org/ quite often. It's a free, in-browser tool that lets you create/edit/export diagrams using markup. Takes some getting used to but I much prefer it to dragging arrows around manually.
amelius
Most designs can't be planarized that easily, so I don't use diagrams.
itsArtur
I like the C4 model because it forces me to think about the right level of abstraction for the diagram's audience. It also has very few core building blocks and thus is very easy to learn. I just wish the tooling around it was better :)
Hypergraphe
Hi, there are several draw.io plugins available on github do use C4 in draw.io if you are not already aware of this.
victor96
We're currently working on tooling at http://icepanel.io which supports the C4 model. Please reach out to us if you'd like to chat about this, we'd love to hear your thoughts.
Rochus
I used a lot of Objectory and UML diagrams in the nineties, mostly for specification and presentation reasons; don't remember when I used one last time; must be more than ten years ago; from my point of view UML is overkill most of the times; usually takes more time to explain to people what all the sophisticated symbols mean than e.g. simple block diagrams; and systems tend to be so big these days that UML diagrams become too big and confusing; we had the same evolution in hardware development; schematic diagrams were almost completely displaced by hardware description languages (such as Verilog) because systems became much too big to be decently modeled with diagrams. EDIT: it's worth taking a look at this article: https://modeling-languages.com/uml-opinions-creators/
Gehinnn
I use drawio, as those diagrams are quite future proof (drawio is open source, very old and you can embed diagrams in svg files) but also very expressive (you can even use latex inside drawio diagrams).

Since I created a drawio integration extension for VS Code, I tend to create much more diagrams during coding, as they are really cheap to create. There is also an extension for IntelliJ and the diagrams work nicely in github readme files. After moving diagrams closer to code, I noticed that it is much easier to keep them in sync with the code base. Especially as PRs changing the code structure can include diagram changes at the same time.

I use them to model simplified class diagrams for documentation purposes, to model data flows, to create primitive mockups, to show the relationship between UI components (as embedded screenshots) and to show component dependencies. I try to follow UML, but I don't care about machine readability and prefer readability over UML compliance.

You can find some uses-cases of those diagrams here (https://dev.to/hediet/create-diagrams-in-vs-code-with-draw-i...).

notRobot
Draw.io is amazing!

It has now been renamed to diagrams.net: https://app.diagrams.net/

Github repo: https://github.com/jgraph/drawio

It's very easy to self-host, especially on Github Pages: https://github.com/jgraph/drawio#running

There's also desktop apps for Windows, GNU/Linux, Mac and Chrome OS: https://github.com/jgraph/drawio-desktop/releases/latest

capableweb
At first, the naming change seems useless. At second thought, it might help with discovery as "draw" is very generic (end up calling it "draw io"). Third thought is why did they chose something generic again, instead of creating a unique name?

The name draw.io seems to be everywhere in the code/documentation/community/stack overflow still and even searching for "draw io" shows "Draw.io - Diagrams.net" which just adds to the confusion.

Probably either names would have been fine, but at least be consistent about it.

Gehinnn
Afaik they only wanted to get rid of the io tld, as it is quite insecure.
pcthrowaway
What makes the .io TLD insecure?
samoraai
From their blog: “ There are two major problems with .io domains:

The first is that the islands which should own the domain suffix, don’t, thanks to a wonderful piece of modern day British Imperialism. If you ever feel the need to donate to us, please give it to a more worthy cause.

Secondly, there was a security issue with the .io domain. In 2017, a researcher managed to take control of four of the seven authoritative name servers for the .io domain. We accept that mistakes can happen, strong processes limit the chances of them happening, but they still can.

However, the domain administrator made no attempt, at any time, to communicate with anyone about the issue. We’ve no evidence to suggest there is anything to be worried about, but the complete lack of communications means we have lost trust in whoever controls .io domains.”

https://www.diagrams.net/blog/move-diagrams-net

kwanbix
draw.io is great, however, isn't the question about what type of diagrams do we do instead of what software do we use to do diagrams? I am confused.
tda
Thanks for the extension! Don't make that meany diagrams but when I do I use it. Much easier than going to the draw.io in the browser as the extension can easily access the files in the source code
jimbob45
Came here to say this. It’s free and it does a great job.
gonzo41
Yeah my top 3 is websequencediagrams, PowerPoint and draw.io All depends on the information I'm trying to convey and the formality, Truthfully, PowerPoint is my goto for explaining flow and quick 'this speaks to that' style network stuff.

I also get a bit of millage from time to time out of the Graphviz online demos. I use those to throw together graph-ish stuff on the fly.

kenoph
Just FYI: draw.io uses SVG foreignObjects for styling the text in the diagrams. That means that to get a proper rendering of the resulting SVG you need to look at it in a browser. If not, it has a fallback text element, but you lose the styling. I lost many hours due to this :/ other than that, I like it a lot
Gehinnn
Sadly, this is a known problem. Theoretically, you can use Chrome headless to render such SVGs into PDFs.
avereveard
I'm mostly producing component diagrams where we detail communication interfaces and services responsibilities; those are stable, long running and broad enough that one they don't become immediately obsolescent and still are granular enough that they can convey useful information to whomever reads them

we also do produce some reverse engineered code map with doxygen here and there, so we can cut down cross dependencies and dependency cycles as the codebase matures

yrgulation
I use draw.io for high level architectural diagrams, both for oop code and infrastructure. When on site i use whiteboards and pictures of them, then if time allows i move them over to draw.io. I almost never draw implementation diagrams. These can be extracted with tools like doxygen.
roland35
I don't use strict UML, but I still find it useful to do work with block diagrams of systems to show relationships of major components.

I used to use Yed, but now I like drawio.