[HN Gopher] The Unreasonable Effectiveness of Sequence Diagrams ...
___________________________________________________________________
The Unreasonable Effectiveness of Sequence Diagrams in MermaidJS
Author : jessems
Score : 172 points
Date : 2023-07-24 10:45 UTC (12 hours ago)
(HTM) web link (jessems.com)
(TXT) w3m dump (jessems.com)
| Vox_Leone wrote:
| 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.
| foobarbecue wrote:
| 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
| rapnie wrote:
| Forgejo [0] (and Gitea) have also implemented it. Or more
| accurate to say, they use Goldmark markdown parser and the
| Mermaid extension [1].
|
| [0] https://forgejo.org
|
| [1] https://github.com/abhinav/goldmark-mermaid
| tootie wrote:
| 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.
| bnjms wrote:
| I think you're nuts :) I find them super helpful for refreshing
| when I need to see the flow for protocol exchanges like SIP,
| FTP, TLS.
|
| I don't know how else you would model that. Words don't
| communicate deeply enough.
| tootie wrote:
| I'm thinking more about business processes rather than
| protocols. I don't think most project involve devising new
| protocols. If I want to diagram the steps involved in, say,
| onboarding and nurturing a user, then the flow will rapidly
| approach a cyclic, undirected graph.
| macmac wrote:
| I think the article links to the wrong marky library. The one
| linked to is a node lib called marky-mark, which does not appear
| to support mermaid. I think the correct link is this:
| https://docs.rs/crate/marky
| w_for_wumbo wrote:
| It's also handy that because its text based, generative AI can
| create the diagrams for you based off of a text description,
| which reduces the barrier to entry even more as you don't need to
| memorize the syntax to begin utilizing it.
| dpflan wrote:
| 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).
| victorbjorklund wrote:
| 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... )
| pragmatic wrote:
| https://play.d2lang.com/?script=qlDQtVOo5AIEAAD__w%3D%3D&ske...
|
| I was going to ask why you don't have a web version but you
| already do. I'm going to play with this more today.
|
| Have you thought about an "auto compile"/live mode where it
| changes as you edit the text? I think this adds a level of
| intuitiveness that would help new users explore.
| hcrisp wrote:
| 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....
| tra3 wrote:
| 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.
| williamdclt wrote:
| If you use Notion, it supports MermaidJS as a comment block. It
| auto-update the generated diagram in real-time. Super useful.
| rcarmo wrote:
| I really, _really_ wish I could generate SVGs of these without
| JavaScript and a headless browser.
| hoosieree wrote:
| 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.
| nequo wrote:
| Have you tried converting the dot file to svg and
| manipulating the svg file in the build process to improve its
| appearance? I'm not sure if it's worth the effort but perhaps
| it's a viable alternative.
| hoosieree wrote:
| Hah, I haven't tried that, but I bet it's possible to do it
| all within org-mode...
| hiyer wrote:
| 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
| victorbjorklund wrote:
| D2 lang (https://d2lang.com) can do that.
|
| My guide: https://victorbjorklund.com/build-diagrams-as-code-
| with-d2-d...
| rgrieselhuber wrote:
| Curious if anyone has experience with large diagrams (100K+
| elements) using D2 or something similar?
| kstrauser wrote:
| I've had a lot of luck with Graphviz and ridiculous numbers
| of nodes. Have you tried that?
| rgrieselhuber wrote:
| A little bit, I'm just not a fan of the way it looks.
| kstrauser wrote:
| That's a perfectly fair issue. Mermaid and friends are
| soooo much prettier.
| ree-san wrote:
| I have used https://github.com/mermaid-js/mermaid-cli
| pbnjay wrote:
| The mmdc tool does this!
| rcarmo wrote:
| I'm looking at its GitHub repo and it lists puppeteer as a
| dependency. There's even a puppeteer-config.json in there, so
| I assume it still requires having Node and running a headless
| browser in the background.
| jrmiii wrote:
| 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
| sp33der89 wrote:
| I really like d2 a lot more than its alternatives.
|
| However the big problem here being that d2 is still quite new
| and isn't as well supported as Mermaid JS
| gpderetta wrote:
| 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.
| jessems wrote:
| As another commenter mentions, the mmdc tool takes care of
| this. I should have mentioned that in the blog post.
| rcarmo wrote:
| Does it do it without needing to have npm and puppeteer
| installed at all?
| aloisklink wrote:
| I'm one of the maintainers of the mermaid-cli project, and
| unfortunately, no.
|
| Mermaid needs a browser's layout engine to run properly
| [1], but I haven't yet seen a library that will help us
| without puppeteer.
|
| And yep, NPM (or another Node.JS package manager) is still
| needed for installation. I was working on trying to bundle
| all of mermaid-cli's dependencies (aka Node.JS, puppeteer)
| into one massive single-file exe last weekend, but it's
| seems we're blocked by missing features in other packages
| [2].
|
| If anyone has any ideas on how to implement these things
| easily, feel free to help-out :) I'm also not a big fan of
| puppeteer, so I'd love to see a way to go without it.
|
| [1]: https://github.com/mermaid-js/mermaid/issues/3650
|
| [2]: https://github.com/mermaid-js/mermaid-
| cli/issues/467#issueco...
| andrewshadura wrote:
| Why is it so difficult to do the layout yourself and
| generate SVG directly?
| ygra wrote:
| My guess would be that text layout and measuring is
| something that's very easy to offload to the browser,
| yet, if you want to do this without, you're pulling in a
| whole lot of other dependencies (text rendering is quite
| complex) that you maybe cannot reasonably call from JS.
| aloisklink wrote:
| That's pretty much it. All modern browsers come with CSS
| layout functions [1], even Internet Explorer did! Pretty
| much every other Web API can be implemented in Node.JS
| using something like JSDom [2], but the CSS layout engine
| is the main missing feature. And the creator of JSDom
| estimated it would take 3-6 months of full-time work from
| a talented engineer to implement something like this [3],
| so this might take a while.
|
| ---
|
| Just to give you an idea of how hard this would be,
| Mermaid let's people use custom fonts, with fallbacks, so
| diagrams can look quite different depending on what font
| people have installed.
|
| The current default font is Tahoma [4], which is owned by
| Microsoft, so Linux desktops usually render the diagrams
| slightly differently than on Windows/MacOS desktops.
|
| People can also have different default font size in their
| browser/OS settings, and that will affect things too.
|
| Finally, you also have things like ClearType [5], where
| the text is rendered differently depending on the sub-
| pixel arrangement of your monitor!!
|
| I think we could get a basic version that partially works
| by implementing only a subset of the layout functions and
| hard-coding one specific font in, but even that would
| still be a fair bit of work.
|
| [1]: https://drafts.csswg.org/cssom-view/#dom-element-
| getbounding...
|
| [2]: https://github.com/jsdom/jsdom
|
| [3]: https://github.com/jsdom/jsdom/issues/1322
|
| [4]: https://en.wikipedia.org/wiki/Tahoma_(typeface)
|
| [5]: https://en.wikipedia.org/wiki/ClearType
| neuronexmachina wrote:
| As an aside, I've been pretty impressed at GPT4's ability at
| generating MermaidJS sequence diagrams for open source projects.
| ASalazarMX wrote:
| It's crazy how normalized powerful LLMs became this year. They
| still seem almost magical, but they're so accesible and
| commonplace they lost their novelty factor too fast.
| jessems wrote:
| Multiple comments like this, I'll try that out!
| crftr wrote:
| I'm a huge fan of riffing on architecture ideas, with
| chatgpt/GPT4, and then asking asking for a representation in
| mermaid syntax.
| mrblues wrote:
| Swimlanes is a simple implementation of the same concept.
|
| https://swimlanes.io/
| [deleted]
| da39a3ee wrote:
| Yes, this is what I use and I can't recommend it highly enough.
| I'll try mermaid but I think swimlanes.io is going to win for
| most use cases. Here's why:
|
| (1) you just open the web app and start typing and you have the
| beginnings of your diagram within 30 seconds literally.
|
| (2) The web app is elegantly and thoughtfully designed, the
| diagrams are beautiful, export functionality is there.
| jimmychoozyx wrote:
| 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.
| Tade0 wrote:
| 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.
| prepend wrote:
| Likewise. I also really like being able to quickly diff diagram
| versions to quickly see what is new since the last version.
|
| That's been so convenient to me, I now strongly prefer
| mermaidjs over more featured tools like lucid or Visio or
| draw.io.
| smusamashah wrote:
| 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.
| NeoTar wrote:
| 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!
| kristiandupont wrote:
| 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.
| jessems wrote:
| Have you tried templates?
| elric wrote:
| 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.
| da39a3ee wrote:
| I highly recommend https://swimlanes.io/ personally. It has
| essentially zero friction between thinking of a diagram and
| seeing the diagram in front of your eyes.
|
| I'm sure Mermaid.js is nice and I will try it for comparison
| soon.
| Pirate-of-SV wrote:
| Github Markdown supports Mermaid OOTB, really useful.
| client4 wrote:
| 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.
| jaktet wrote:
| Have you tried draw.io?
| quietbritishjim wrote:
| 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
| yurodivuie wrote:
| +1 for Plantuml. It has a great ecosystem, but there are
| certainly tradeoffs vs using mermaidjs, because of their
| different compilation models. Mermaidjs seems to look nicer out
| of the box as well, but usually that's not the point for a
| sequence diagram.
|
| I'd use whichever works for your ecosystem and diagram
| lifecycle. The syntax is similar enough that I think the
| diagram creation constraints are often a bigger difference.
| smusamashah wrote:
| https://sequencediagram.org/ is the best sequence diagram tool
| like that. It does diagram-to-text to if you draw a line etc
| with mouse. Can right click and have context options too.
| dilawar wrote:
| Checkout kroki as well which is collection of various tools
| including plantuml, tikz, mermaidjs, graphvi etc.
|
| As a bonus, niolesk is a very good frontend on top of kroki.
| You get an editable link of your diagram which you can share
| with teammates.
|
| You can find docker image on github running kroki and niolesk.
| chrisweekly wrote:
| I came to say the same thing; kroki is the powertool of
| choice in this space.
| jph wrote:
| More examples of sequence diagrams with PlantUML, with
| renderings of dividers, actors, databases, etc.:
|
| https://github.com/joelparkerhenderson/plantuml-examples
| inetknght wrote:
| I've used PlantUML. It's very nice.
|
| However, it gets to be difficult to use if you've got
| complicated scenarios. It's very difficult to depict
| parallelism with PlantUML.
| jessems wrote:
| Cool, I'll check it out.
| Vgoose wrote:
| This is my go to diagramming tool. It takes a lot of little
| tricks to get things to turn out exactly how you want, but
| they're not required. It communicates information just fine.
| The tricks are only required if you care about aesthetics.
| zelphirkalt wrote:
| It does look nice, and covers most things, except for life
| lines. Is there a way to add life lines?
|
| And why do so many tools choose to ignore life lines and
| provide incomplete sequence diagrams? Perhaps it gets really
| complicated to express in such a simple way as the examples do?
| quietbritishjim wrote:
| It has those! They're under "Lifeline Activation and
| Destruction" on that page:
|
| https://plantuml.com/sequence-diagram#5cc0040514e70f7b
|
| You can even have two active on the same lane at the same
| time, as shown in the second example on that page.
| anticodon wrote:
| I would like if PlantUML would be implemented in some lighter
| language. JVM size and startup time is atrocious. You can
| easily notice latency caused by it even on modern hardware when
| rendering diagrams locally. In CI/CD it takes too much time to
| install JRE and run PlantUML. Probably, I can optimize it to
| some extent, but if it were implemented in another language, I
| wouldn't have to spend my time on it. Everything Java related
| is a monstrosity in size and consumed resources (CPU, RAM).
| The_Colonel wrote:
| I believe PlantUML was basically the inspiration for MermaidJS.
| A huge advantage of MermaidJS is that it can run in the
| browser, though.
| atoav wrote:
| And if you start a markdown codeblock like
| ```mermaid graph TD; A-->B ```
|
| Many things that support markdown (e.g. github, gitlab,
| typora, ...) will render the resulting graph.
| lelandbatey wrote:
| That features is also a feature Mermaid/Markdown renderers
| have borrowed from existing uses of PlantUML. You've been
| able to embed PlantUML in a Markdown block in Gitlab (and
| have it rendered inline as an image) since before MermaidJS
| ever existed. Github's embedded MermaidJS feature is years
| late.
| chrsig wrote:
| unfortunately, you need a PlanetUML server when using a
| self hosted gitlab install.
|
| running directly in the browser is, imho, the best
| feature of mermaidjs
| ttfkam wrote:
| 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
| AdieuToLogic wrote:
| Agreed. I'd also add deployment diagrams[0] to the "pretty darn
| useful" list.
|
| 0 - https://www.uml-diagrams.org/deployment-diagrams.html
| jessems wrote:
| I'll give those another look, thanks!
| The_Colonel wrote:
| Yes, there are many useful diagrams in UML, but a lot of them
| (e.g. entity diagrams) don't map well to text based formats
| such as MermaidJS, because the positioning is quite important
| and MermaidJS often won't guess correctly.
|
| Meanwhile, sequence diagrams map very well from the text
| description.
| MilStdJunkie wrote:
| I've gotten some mileage out of the PlantUML JSON
| visualization, as well as the REGEX graph, gantt, salt, and wbs
| for org charts.
|
| XEARTH is also pretty neat, if you don't want to bring in a
| full mapping API just to show a point on a map. I realize it's
| a pretty crappy map in XEARTH, but the point is, I don't always
| need a _good_ map.
|
| Mermaid's nice though. I love the git graph - I use that thing
| every day. If I'm not dealing with ITAR data I just render
| everything remote through the kroki service, and take what I
| need from each graph spec.
| WirelessGigabit wrote:
| The popularity of MermaidJS makes me wonder why I cannot have
| that natively in Confluence.
| tra3 wrote:
| Confluence has a mermaid js plugin [0]. This is in fact why I
| switched from plantuml to mermaid.
|
| 0: https://marketplace.atlassian.com/apps/1214124/mermaid-
| plugi...
| pjot wrote:
| I wonder why Confluence doesn't include popular features all
| the time.
| rapnie wrote:
| 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.
| nativecoinc wrote:
| 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.
| jessems wrote:
| OP here, did not know of the existence of "The Unreasonable
| Effectiveness of Mathematics in the Natural Sciences"! I agree,
| that's a whole other level.
| nh23423fefe wrote:
| A fine example of a meme spreading untethered from its
| source.
|
| Can I ask why you chose that title template?
| mrWiz wrote:
| 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.
| chrisweekly wrote:
| Have you seen xstate's visualizer? https://xstate.js.org/viz/
| mrWiz wrote:
| I hadn't seen that, thanks for the link.
| giraffe_lady wrote:
| Last time I tried this it unnecessarily crossed a lot of the
| arrows between states. Turned a diagram of a moderately complex
| real world SM into an incomprehensible tangle even to
| developers familiar with the actual implementation. Does it
| still do that?
| mrWiz wrote:
| I haven't run into that, but maybe that's just because I
| haven't tried anything too complex yet.
| agumonkey wrote:
| i love mermaid but i find sequence diagrams too thin on
| information, a graph view always feels like the right amount of
| data
| dpflan wrote:
| Please elaborate. The amount of information provided is up to
| the creator of the diagram...
| agumonkey wrote:
| a sequence is a projection of many interactions between
| modules, which can often be described fine on a 2d graph
|
| i hope it makes a bit more sense
| Veuxdo wrote:
| Not the OP, but sequence diagrams show individual scenarios,
| by definition. And there can be a _lot_ of scenarios in a
| complex system. Thousands, perhaps.
|
| Relation (box-and-line) diagrams show the static relations
| between resources in a system, not individual scenarios. This
| typically gives a better overview.
|
| Long story short, you need both. If you want the long story,
| I wrote (a lot) on this a couple of years back:
| https://www.ilograph.com/blog/posts/the-two-fundamental-
| type...
| dpflan wrote:
| - Thanks for the details and resources. Where is the
| "graph" in the post? When someone says graph I usually
| think of a pretty basic thing with nodes and edges.
|
| - What're your thoughts on C4?
| BaculumMeumEst wrote:
| 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.
| hbcondo714 wrote:
| 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
| galkk wrote:
| In general I'm fan of text based diagramming tools, but with all
| mermaid diagrams that I've tried to do (flowchart, class
| diagram), you hit syntax limitations way too early...
|
| Also lack of consistency in common things.
| Veuxdo wrote:
| You probably shouldn't convert diagrams from HTML to PNGs since
| you lose all accessibility. SVGs might be better; I'm actually
| not at sure.
| ygra wrote:
| When rendered as an image, they don't differ; you'd have to
| inline the SVG DOM in your HTML to make a difference. And yes,
| then you can have screen readers reading the text, ARIA
| attributes to better describe certain parts, etc.
|
| That being said, SVG is likely still a better option than PNG
| for its scalability alone. At least for this kind of content.
___________________________________________________________________
(page generated 2023-07-24 23:01 UTC)