These tools show up from time to time here, and I can appreciate the technical side of things and effort put into building the tool. However, I cannot imagine using something like this in practice - either at work or for my own uses. It's so much easier just to select, drag and drop graphical elements instead of spending time learning a specific markup language and typing everything out, hoping that the elements will appear approximately where you wish they would. Maybe it's not too bad for very simple diagrams but unmanageable for anything complex. All in all, I think it does not solve any problems and merely adds an additional layer of complexity.
I use PlantUML a lot, for communicating complex technical designs for juniors to implement for example, or simply for documentation.
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.
I have been using PlantUML a lot. For me the effort of drawing a diagram in an external tool and then exporting it seems like such a waste compared to adding source code that compiles into the diagram I need.
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.
Yep, GPT is nice for speeding up the process. I've gotten in the habit of actually speaking out loud the desired flow of events in a system and transcribing it, and then turning that text into sequence diagrams with GPT4.
These markup languages are often not competing with "making a single diagram with drag&drop", though. Lets say you're making lots of variations, then having it in a specified format for easy changes is nice. Or diffing changes. Or programmatically generate them.
Lets say you're making lots of variations, then having it in a specified format for easy changes is nice. Or diffing changes. Or programmatically generate them.
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.
These specialized grammars attempt to strike a balance between human-readable and machine-readable. JSON is a terrible solution because you'd have to have an id + dictionary, then a list of relationships. Basically, no human is ever editing that.
> It's so much easier just to select, drag and drop graphical elements instead of spending time learning a specific markup language and typing everything out
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.
>There's an analogy to programming: sure we have visual programming tools but who uses them?
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.
> Maybe it's not too bad for very simple diagrams but unmanageable for anything complex
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.
> 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've seen tools that work like this - Microsoft's earlier kicks at entity framework tried to do it for SQL table block diagrams. They would constantly get out-of-sync as merges happened and were generally a pain to manage.
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.
The issue with graph engines that manage the layout themselves is that it becomes very messy the higher the number of nodes you have. I've experienced this with Mermaid.js and Obsidian.
Still, I'd rather have textual hints about layout than explicit drag-and-drop. Stuff like "boxes a1, a2, a3 should be presented sequentially" or "box b1, b2, b3 are tightly related and should be presented close to each other" and "box c is the root of its tree" and stuff like that.
I use mermaid sequence diagrams all the time and much prefer them to using whatever app. GitHub can render them which is nice. Refactoring them is easier than dragging 20 boxes around too in my opinion. I've done a couple Gantt charts. I see they support c4 which I need to try.
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.
I wish there was a way to easily export mermaid diagrams to PNG or PDF. Right now sharing the diagrams, especially ones that scroll, is a pain in the ass.
This could be rewritten to save locally or an endpoint you run: https://github.com/kordless/mitta-screenshot. The code is in background.js. Just fullscreen the graph then click the icon.
Mermaid for message sequence diagrams is amazing -- we recently added 'GPT for diagramming' support to Louie (conversational data & compute notebooks), and combining these rich DSLs with conversational AI & an interactive UI is a pretty cool & time-saving experience because it can bootstrap a lot
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.
7. You can put them in the source where they are relevant.
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.
> 7. You can put them in the source where they are relevant.
> 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.
> You can build tools to automatically generate these diagrams from existing software quite easily.
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.
I use graphviz dot (which is similar to this tool) specifically so I don't have to fight with getting the arrows right, manually fixing each one, in a visual editor.
Either way, regardless of whether it's easier - the software world is driven by the power of plain text. Text is king. Text lets you diff, lets you git, lets you pull-request, lets you grep, etc.
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.
I once worked on a project where the state of a file was basically a graph (similar to programming languages where users actually manipulate an AST). Our tests would simulate changes on that graph and check invariants every for every build. We'd spend hours of our weeks looking at long logs describing steps to reproduce a thing.
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.
> Maybe it's not too bad for very simple diagrams but unmanageable for anything complex.
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.
Text-based versions are much better for accessibility. A screen reader or text to speech software can describe a textual representation of a diagram much better than your WebGL equivalent on a zoomable canvas.
I decided to ask the bing bot to type one out for me, and it told me "no". When I asked it why, it told me it was because it wasn't "creative" so it wrote me a poem in Python. I then asked it to write a diagram that was funny. It told me "no" because it wouldn't be creative.
GPT4 was surprisingly good at generating dot (Graphviz) files when I tried, and even managed to do reasonable visual layout of nodes (it's an interesting test, both because reasoning about visual constraints in text is tricky and because good diagram layout algorithms are complex)
I think the big gain here is that’s it’s LLM-readable. If you make a WYSIWYG GUI backed by a plain-English format like this, it becomes MUCH easier for LLMs to understand and help you.
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
