It's nice to have your diagrams as readable code which you can check in with the rest of your git repository and embed in READMEs, and the syntax is really intuitive and easy to learn. I haven't made the comparison with this particular tool yet, but in general I'd recommend this practice of including diagrams with your docs.
As a nice bonus, GPT-4 is pretty good at generating valid PlantUML. I have given descriptions of the diagram I want and gotten results that have gone into docs unchanged.
But in all those cases wouldn't it better to have something with an actual API in a programming language you are familiar with? Or at least a tool the takes something like JSON, for which there already are great tools for parsing, generating and manipulating.
You state this like a fact. A GUI might be your personal preference but markup is preferred by many. It takes me an order of magnitude longer to learn where all the buttons are than it does to internalize markdown syntax from a few good examples. In a GUI you spend time futzing around with visual details, In a markup chart you spend time building and communicating a coherent mental model. The difference in output quality is apparent to me.
There's an analogy to programming: sure we have visual programming tools but who uses them? they break down when things get mildly complex. A markup driven charting tool lets me edit in the comfort of my chosen IDE, check it into source control to collaborate, renders live instead of checking in an image artifact, and has clearly-defined semantics (ie not just a pile of incoherent boxes and arrows). IMO, it's superior in every way except fine-grained control of the layout (which is a fine tradeoff for me - I want my readers to focus on content - consistency is more valuable than styling). If your purpose is communicating complex ideas (not making a pretty picture) markup-based charts have some distinct advantages that you just can't get from a point-and-click interface.
I really don't think this is a good analogy. Clearly presenting an idea / architecture / model / workflow at a high level by creating a graphical representation is quite different than making an application does a lot of things at a low level (e.g. handling user interactions, processing data, providing GUI, communicating with other systems, handling errors).
I agree there may be some benefits to that but I guess it also depends on what kind of diagrams you are making. For example, I would never ever draw UML diagrams in markup. I want to be in control how elements look, where they are placed, where and how lines are drawn and where and how they are shown. In my experience, automatic placement even on GUI diagramming tools suck 99.9% of the time.
On the contrary, I use drag&drop tools for very simple diagrams but prefer using PlantUML for anything complex because its text-based interface makes it easy to generate, diff or store in a git repository. The best of both worlds would be a text-based tool to hold the semantics of your graph, and then a drag&drop interface to fix the layout.
Exactly this, I wonder why no one has come up with it yet. Maybe you could embed the layout details like coordinates of elements inside the markup in a separate section?
I'd rather a tool just let me give it hints of "this is an important block put it somewhere high visibility" and "this is semantically the root of a tree" and stuff like that, then just focus on having a good clean layout engine.
We don't have many options of approved diagramming software where I work though. Omnigraffle which I don't care much for, and Visio which doesn't work on Mac. Maybe I'd have a different opinion of we had something proper.
For random boxes and arrows I do typically go for Excalidraw though.
Example from work where the original took 1-2 hours: https://www.loom.com/share/aa388d49f28d471d89e3d8c048e9c0a0
It's amazing to think where these will be even 6mo from now
1. You can build tools to automatically generate these diagrams from existing software quite easily. I've used tools like this to generate diagrams that were impractical documentation (150+ sheets of A4 when printed), but showed class or module dependency hotspots in a way that would have taken weeks to understand from the code alone: a picture speaks a thousand words, and getting your code to give you a picture is useful.
2. You can version control them - and see change history - more easily through a markup/code approach than a GUI approach. When teams collaborate over a complicated piece of design, being able to see who contributed what and when in a diagram is as useful as it is seeing it for a piece of code. I'd argue the first responsibility of a programmer in a modern team is to communicate, and to do so in a collaborative fashion. Code, tests, documentation, should allow easy collaborative understanding, editing and iteration. Diagrams that don't have editable markup make this harder in a small way.
3. The semantics of the markup actually make you think through what it is you're trying to express. It's easy to draw a line connecting two shapes but what does that line actually mean? I find when I'm typing up markup for a diagram, this becomes something I more consciously consider.
4. A markup standard means there is likely to be multiple tools that support the reading, editing and creation of the artifacts you create. Some people feel it's easier to use a WYSIWYG word processor, but I think we can all agree that Markdown is a useful innovation that has stimulated some experimentation and development in the text editing domain.
5. Most "hand-drawn" GUI-based diagrams look ugly (most programmers can't design diagrams well), but using an algorithm to make layout choices provides consistency and better layouts.
6. Many "hand-drawn" diagrams are full of style inconsistencies. With a markup + parser = diagram approach, you can enforce a house style, update that style easily, and everybody's diagrams in a doc look aesthetically similar rather than each individual's personal preference on line weights and arrow styles. It's a bit like separating HTML and CSS - hard to do in a GUI-only approach. In larger teams with a dev wiki, all the diagrams looking similar is just nicer.
YMMV, but I'd give this approach serious consideration - this tool looks great, but there are others, and it's worth evaluating them if one doesn't impress you. I'm a graphviz guy, but I might consider looking at this more closely.
FWIW, Doxygen does diagrams-from-code out of the box. It's mostly a code documentation/literate programming tool, but also useful for these reverse engineering tasks starting from an existing codebase.
Got a hairy state machine? Stick a comment at the top with something like nomnoml's syntax and anyone can follow what's going on without having to trace through the code.
> Got a hairy state machine? Stick a comment at the top with something like nomnoml's syntax and anyone can follow what's going on without having to trace through the code.
For that use-case a markup graph language is a poor solution. Use https://asciiflow.com instead to produce something that people can digest without needing a third-party tool that may not even exist anymore.
Look at the popularity of Markdown, a syntax that is just "simple html but it's easy to read in plain-text form". Or YAML, which is just "JSON and XML that doesn't make your eyes bleed, but has the worst type-inference ideas ever".
Yes, GUI tools can help. Doing image-links in Markdown is a PITA. Ditto good-looking tables. But still, the idea of "human-friendly-text-first" formats is valid.
Doing the same for UML just makes sense to me.
Now obviously there are implementation details I disagree with, both in the format and the renderer. But the idea is sound.
One day, someone on our team had the brilliant idea to log the state of the program as a dot graphviz text file and just render it with the tool. Our debugging effort was instant all of a sudden.
Sometimes these tools are amazing at visualizing data more than at building diagrams. It's surprisingly easy to generate valid text files programmatically. Note that I'm talking in general about this class of tools, not nomnoml specifically.
Yeah, the problem with these sort of layout algorithms is that they don't have a sense of proportionality.
I wonder if LLM can do this better. I've tried with 5 relations from this example one and ChatGPT comes up with this:
Place "Jolly Sailor" at point (1, 1).
Place "Pirate" at point (2, 1).
Place "rum" at point (3, 2).
Place "mischief" at point (2, 0).
Place "Marauder" at point (3, 0).
It looks okay, but I haven't checked with anything more complicated.[0]https://www.ilograph.com/blog/posts/its-time-to-drop-drag-an...
:sigh: technology.
And I think they’ve gotten to the point where “how can LLMs change this workflow” is a much more impactful question than basically any other UX improvement