I can highly recommend PlantUML as a simple language for creating sequence diagrams. It also supports other UML diagram types, which, despite what the article says, are also useful sometimes (so long as you don't worry about every last silly detail that's specified in the standard).

   @startuml
   Alice -> Bob: Authentication Request
   Bob --> Alice: Authentication Response

   Alice -> Bob: Another authentication Request
   Alice <-- Bob: Another authentication Response
   @enduml

https://plantuml.com/sequence-diagram

    ```mermaid
    graph TD;
      A-->B
    ```

I guess it’s effective because it is similar to Markdown and other lightweight stuff: things like bullet items are just written like bullet items, with hyphens (or similar). You write it how you want it to be displayed. Granted for a diagram it’s more complicated since it’s a graph and not a tree, and you write it with declarative arrows rather than as ASCII art, but perhaps that in practice strikes a nice balance between being non-finicky and at the same being simple enough (syntax-wise) in order to deal with.

That aside the “unreasonable effectiveness” allusion to “The Unreasonable Effectiveness of Mathematics in the Natural Sciences” is clearly overwrought. Let’s not get ahead of ourselves.

> Reaching for code to solve my code problem seemed like something that would only appeal to someone that loves code so much that they're probably no good at visualizing.

It looks more like a pseudo-markup to me.

I prefer D2 lang over MermaidJS for diagrams because the diagrams just "look" better and you have more ability to customise the look. And after all if the purpose is visualisation the visual matter.

(Shameless plug: Intro to D2 https://victorbjorklund.com/build-diagrams-as-code-with-d2-d... )

MermaidJS is fantastic. I love that github has integrated it, but I wish they would update so that the markdown-in-mermaid support worked. If you agree, say so on the issue I posted: https://github.com/orgs/community/discussions/61266

I really, _really_ wish I could generate SVGs of these without JavaScript and a headless browser.

I really enjoy MermaidJS. I've been trying to shoehorn representing vlan flows over switches recently and haven't been very successful. My basic goal is to show [p1]switch1[p2] <------> [p9]switch3[p12] in a graphical manner (and more intermediate switches). MermaidJS kind of works. I'm tempted to use something like Visio or Google Drawings but they take too much manual work.

An alternative to using Marky to render the Mermaid diagram which I did not see anyone mention is this VS Code plug-in. I use it and it is quite nice:

https://marketplace.visualstudio.com/items?itemName=bierner....

I've used MermaidJS to create sequence diagrams for the project I'm working on and it helped tremendously in discovering what a heap of steaming manure I wrought.

A previous company I worked at had a way to translate logs into sequence diagrams - specifically in this case SIP message flow. by searching for an ID you could see all of the services which interacted with the message flow, and by clicking on the arrow a full version of the message which was sent.

It was amazingly useful for diagnosing problems. I wish more logging systems were able to visualise flows through a system of micro services so well!

I wonder if the URL in the article to Marky shouldn't point to https://lib.rs/crates/marky instead of to the NPM package.

I wish there were a CL/Clojure alternative to MermaidJS with a predictable interface so I could build diagrams at the REPL avoid searching/remembering what weird DSL to use when making diagrams. MermaidJS does seem to be a solid tool though. I use Omnigraffle when I want more control over the result.

Swimlanes is a simple implementation of the same concept.

https://swimlanes.io/

For an easy, out of the block, self-hosted experience, allow me to recommend:

Docusaurus.io framework. Why? It's compatible with MermaidJS-- simply run 1 install command, and setup 2 config settings-- shown here: https://docusaurus.io/docs/next/api/themes/@docusaurus/theme...

Docusaurus provides: Docs, Blog, Pages. Via Markdown. And for pages, it even allows basic JSX (reactjs style components).

Lately I've really been enjoying the combination of Docusaurus & Mermaid to document my personal projects.

I like Draw.io for UML but I recently found it easier to do a sequence diagram showing a Stripe integration with actors, activations and notes in a few lines of Mermaid markdown on a GitHub readme: https://github.com/hbcondo/revenut-web#-workflow

But that diagram just renders as code via GitHub Pages:

https://revenut.com

I have found these fun to work with, and ChatGPT has been pretty useful to play with: using it take code and create a sequence diagram, take a sequence diagram and create code (in one language, then another). It's pretty interesting and code generated can be tested so this feels like a good workbench to have for development. I am looking forward to trying Copilot Chat which should have these same capabilities (I hope).

I really like using Mermaid to create state diagrams. I'd been looking for a tool like it for quite some time, and I think it slipped under my radar because it's more focused on sequence / flow diagrams and doesn't hype its state diagram capabilities as much. Using a text-based tool for this is so much better than my previous workflow of Visio or Powerpoint.

I have used Mermaid diagrams quite a bit lately because ChatGPT can generate them. It's been an easy way to get it to visualize things before I have access to the image generation stuff. It works really well, try it if you haven't!

I only wish the renderer could render "sketch" style like Excalidraw, I don't like the default appearance. Obviously a small detail, though.

The article claims that sequence charts are the only useful thing in UML. What about:

Entity diagrams, especially for database ERD

Timing diagrams (think: Gantt)

Interaction/flow diagrams

Use case diagrams

As an aside, I've been pretty impressed at GPT4's ability at generating MermaidJS sequence diagrams for open source projects.

Maybe I'm nuts because I've never found these useful. If you actually want to model a real-world scenario, you'll end with an arrow from every system to every other system to the point that it's meaningless as a visualization.

My own quick and easy Mermaid diagramming page I knocked up a few years ago and stuck on Netlify, and which I (and a few others) use very frequently:

https://sequence-diagrams.netlify.app

Note the credit on that page to bramp.github.io who did the hard work with the JS library it uses. And when you find UI issues remember it was a quick tool knocked up years ago and forgive me.

Before I switched to Obsidian for note taking, I'd been using UMLet (for some 20 years!) for all my UML needs. Its syntax for sequence diagrams is similar to Mermaid's. But now that I'm using Obsidian, I've switched to Mermaid. I see some people mentioning PlantUML, but I rather dislike that it required a rendering service last I tried to tinker with it. Mermaid does not.

I've had a good time with sequence diagrams in college. It is really pleasing to build them.

I entertain the idea that AI [CNN + TNN] can finally fulfill the ultimate UML promise: build code from diagrams. In a certain way, it's easy to see AI trained to ingest diagrams as logical sequences of prompts. With a little effort it is already doable with current tech.

A list (that I occasionally update) of similar text-to-diagram tools that work from browser https://xosh.org/text-to-diagram/

I have noticed that some tools don't allow exporting diagrams anymore or have a watermark on them now. Need to add that info someday.

Slight aside: does anyone know how mermaid/planutml layout functionality is implemented? I'd like to do something similar (but much simpler). I have a few entities (boxes) that are part of a DAG, and I'd like to lay them out somewhat optimally.

It's not the interesting problem that I'm trying to solve so I'd love to reuse something if I can.

Have you looked at d2lang - it supports SVG output: https://d2lang.com/tour/exports/

The syntax is a bit different though, so it depends on where your source is coming from, see here: https://text-to-diagram.com/?example=sequence&b=mermaid

D2 lang (https://d2lang.com) can do that.

My guide: https://victorbjorklund.com/build-diagrams-as-code-with-d2-d...

Currently I generate graph diagrams for papers and blog articles in emacs with graphviz, I wonder how mermaid.js compares in that workflow.

The default styles in mermaid look a little nicer than graphviz, which might be enough to motivate me to try it out. When/if I do, I'll probably try with this emacs package: https://github.com/abrochard/mermaid-mode.

Check out seqdiag, part of blockdiag [1]. It's python-based and uses graphviz (AFAIK) to generate sequence diagrams in SVG. I've used it several times and found it very good.

1. http://blockdiag.com/en/seqdiag/index.html

Having to use npm did put me off initially (as I had never used it, or JS, before), but it was quite painless, and now I have pretty sequence diagrams inline my org-mode docs. Its is about a billion time better than using the confluence builtin WYSIWYG graph builder.

As another commenter mentions, the mmdc tool takes care of this. I should have mentioned that in the blog post.

I have used https://github.com/mermaid-js/mermaid-cli

The mmdc tool does this!