+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.

PlantUML is great but it renders Statecharts in a non-obvious manner.

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.

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.

I only used the Sequence diagrams because they are super useful and the syntax is very intuitive. PlantUML is great

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.

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.

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! :)

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.

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