Maybe PLANTML => PlantUML?

Anyway, PlantUML is my go UML tool because it is a markup language that can be version controlled by git.

And embedded in Asciidoc!

Interesting thing to know : it's rendered on gitlab.com[1]. so you can directly embed the plantuml code within your README and see the diagram.

[1] https://gitlab.com/gitlab-com/gl-infra/infrastructure/issues...

This is definitely one of those things I wish GitHub would “backport” from GitLab.

I really like plantuml, but I just wish there was a way to give layout hints to the engine.

You can sort of specify the direction of arrows, but since everything is a fluid layout, changing those in bigger diagrams behave very chaotic and unpredictable... I very often I just end up using other manual tools to paint those diagrams.

There are actually a number of layout engine hints available for compact, minimize crossings, hard angles instead of curves, top/down vs left/right, and using hidden lines to force specific relationships.

It's scattered about a bit through the manual, but you can achieve most things you need.

Really, there's a Zen of PlantUML where you stop trying to control it and focus on defining the relationships.

Thx. I will take a look at those.

What I would like is way to specify start and end row and column number of nodes. That way it would be more predictable and changing the relations of two nodes does not cause everything to change.

In some diagrams you can use ->, -->, --->, -...-> to specify "ranks" between connections. The layout engine will space accordingly, depending on the top-down or left-right hint.

Yes, especially for statecharts, they get rendered in an ugly manner, totally different from how someone would manually lay them out.

Sequence diagrams come out all right, but I wish if there was some provision to lay diagrams out for automatic page breaks for a4 size paper, for example.

We’ve started to embrace PlantUML in our Systems and Software engineering teams at work.

One nice feature of this markup language is creating diagrams programmatically. We wrote a small python tool that will take a State Transition Table (States cross Events) and create the diagram. I have found it helpful to start from the table to ensure States and Events are well defined and all options are considered, but once that is done the diagram is also quite useful for discussion.

Things that we have found helpful are the MediaWiki plugin and the Word plugin.

We’ve also started adding unique identifiers to all diagrams across our large development program, and keeping all diagrams in one central spot. That alone has been almost as useful as PlantUML.

Can you expound upon how the unique identifiers are used and how the central repo works?

It is REALLY nothing exciting or novel, sorry to disappoint.

I got tired of finding documents with a figure we needed somewhere else and hunting for 15 minutes for the source material.

We number the figures PRJ-FIG_0001 and have the source files in a top level shared folder (or svn/git). Note it’s important to have the figure id in the figure itself as well as the file name so when it’s imported into a doc the ID is embedded in the figure itself.

I think the submission should say "PLANTUML" (adding "U").

True

I use this often enough but it's rather tedious and the diagrams don't look very polished unfortunately

They suffer from formatting issues and are generally more trouble than anything to grapple with

It's probably best for sequence diagrams but activity diagrams with swim lanes and things are quite a chore to implement in an aesthetically pleasing way

Skinparam definitions really help to improve the polish. You can even create templates.

The only issue I've really had is controlling the arrow paths.

I have followed PlantUML for a long while, but mostly use OmniGraffle to make UML sequence diagrams and occasionally high level class diagrams. I wrote a UML book with Paul Harmon many years ago, but now I only use UML a bit.

I will give PlantUML another try since OmniGraffle is an overkill for the simple diagrams I make now.

I have been using WebSequenceDiagrams [1] for years. Love it. It is declarative and simple, and works really well. The syntax seems similar but not the same as the OP article.

In a readme's or wiki page for an epic/story I often usually use a copy of the diagram image, with a link to edit the text/markup, or the text just in a collapsed wiki element. Though there are now also plugins for Confluence and more I believe.

[1] https://www.websequencediagrams.com/

Seems to me they just use plantuml internally anyway and style it differently.

Reminds me of "https://mermaidjs.github.io/" I've used mermaid for basic network documentation and simple routing diagrams. And Mermaidjs has a viewer plugin for AtomIDE

> Reminds me of "https://mermaidjs.github.io/"

Why do you have to put an URL into quotes? You force everyone to manually remove it first because like this the link is broken.

Also to save other people some work: https://mermaidjs.github.io/

Is there any viable alternatives to PlantUML out there?

I want there to exist a simple format that I can put under version control that gives me neat looking diagrams – without requiring me to run a Java based server component.

Monodraw [0] and such are nice, but the diagrams are neither nice nor easy to change without having access to the editor.

[0] https://monodraw.helftone.com/

I have embraced the blockdiag series of programs, which include seqdiag, actdiag, and nwdiag. There is a bit of a learning curve, but once you learn to customize things well it works very well. There are limitations but I got so fed up with Vizio a few years back I was determined to focus on the kiss principle.

http://blockdiag.com/en/

awesome! just bookmarked. i am going to try to translate some existing diagrams using that tool because the images look nice.

btw, the repo isn't showing any picture only the documentation does. that could be improved!

The diagrams on https://www.dns.cam.ac.uk/servers/reshuffle-2018.html are static images that are pre-rendered as part of the overall site build process. No need for java on the server :-)

Graphviz is pretty great for creating diagrams, though if you have specific style needs it can require a good deal of boilerplate.

PlantUML actually uses graphviz for some of the diagram types. You can also embed graphviz code verbatim in plantUML diagrams.

As far as I remember, GitLab supports rendering PlantUML diagrams.

On GitHub, you can use a trick to render the diagrams using the public PlantUML server, which works only is your diagrams can be public.

I have a script that renders the diagrams on a project which I run occasionally and it has worked ok for me.

I’ve gotten good results from MetaUML: https://github.com/ogheorghies/MetaUML. It is TeX-oriented, though.

it's amazing that after all these years diagramming on the computer still hasn't got solved. it's like todo lists and calendars. every now and then, there is something new.

It's a command line tool that renders to raster or vector formats, you don't need to run a server.

I love PlantUML. It’s made my job a lot easier and I love the whole documentation as code.

I’ve written a converter for it too. https://www.npmjs.com/package/pcomp?activeTab=readme

Disappointingly, it looks like it doesn't support mathematical diagrams other than via embedded math-specific languages. I continue to want a markup language for hypergraphs, categories, finitely presented monoids, etc.

Isn’t TikZ the right answer for that kind of thing?

No. TikZ is only for drawing, but diagrams are proper objects with properties and data, and we should be able to manipulate them, not just display them.

I want to make diagrams like the ones on this page - https://www.google.com/amp/s/creately.com/blog/diagrams/aws-... - but I want to have a way to define them in a text format and version control and modify them easily.

I’ve tried doing this with PlantUML but never got it right. Is there a tool like PlantUML that is specifically for architecture diagrams like the ones above (custom icons, etc)?

Not sute if that would fit all your requirements, but I'm sharing just in case

https://mermaidjs.github.io/

Thanks, I looked at it a while go and had some trouble getting started. I'll try it again.

PlantUML allows you to create deployment diagrams, but this one from AWS is hand-drawn, it takes too many liberties with the layout.

Yeah, I do all of these things by hand today as well. It is very time consuming especially when I want to make changes. I’d be willing to accept more constraints if that’s what I have to do but my current attempts with PlantUML can’t get close to the look I’d like even for simple diagrams unfortunately.

There’s also a good VS Code plugin with live preview update.

I like PlantUML but have been disappointed by the quality of its vector output options (SVG, etc.). I found that things rounded corners tended to be rendered at limited resolution, which becomes apparent if zooming in enough.

SVG doesn't have an intrinsic resolution; that's determined by the rendering device. The SVG could be incorrect, but I don't think you can blame plantuml for your device rendering at inadequate resolution.

It may be exporting a PNG or JPEG embedded into an SVG.

This one has zero comments because developers are allergic to diagrams :)

Might or might not be true. But I'd say producing good diagrams is implicitly mandatory if you want to advance your career.

I didn't use them much as an individual contributor, but as a lead, I rely on them all the time to communicate ideas.

PlantUML makes it so easy to do so.

I spend my day trying to convince many developers they should engage in formalized design at all. Big fan of diagrams here.

Same here, with little success. Often people want to find some tool to generate diagrams from the code, which totally misses the point.

Still, I use them in my projects and they help me very much.