I found Mermaid thanks to you Arjan, but I eventually tried using it for a project using mypy typing and I couldn't find a way to have it show the type of non-primitive typed objects. I ended up finding PlantUML as a way to still have the benefits of Mermaid but with that additional functionality (and I was surprised at how little work was required to reformat the markdown to switch.)
I find that for higher level diagrams Mermaid is the way to go. Drawing tools are much more flexible, but that's also a disadvantage because we have to waste time selecting and placing the shapes, connectors, spacing, etc, all of which are unrelated to the end goal. I only use drawing tools sparingly. By the way, you can use CSS to prettify Mermaid, but again, consumes time away from what we usually want: coding 😅
Same here. I do like Mermaid as a part of a design/feature document, but really aimed at high-level descriptions that are quicker to see in a diagram than inferring it from the text.
I like mermaid for simple tasks that I know aren't going to become any more complicated in the future, however it has a number of shortcomings that make it simply impossible to use for anything more professional. In short, it's good for basic flowcharts, but almost every other type of diagram is broken or doesn't have pretty fundamental diagram features implemented. Here are a few serious shortcomings I can think of off the top of my head: 1) The function duration markers on interaction diagrams are essentially broken (and I think the problem is with the way the syntax is structured so it's not even easily fixable). Go try and implement an action that happens within the time that another action is happening (e.e try making a diagram for the observer pattern). You can't do it. 2) For a number of diagrams, certain labels are required to be single words which has caused me some headaches. 3) There's no "subgraph" type feature implemented for class diagrams, (as there is for flowcharts,) so it's hard to show how a group of classes (eg a module/package) interacts with another. 4) There's no option to add code snippets within class diagrams.
At every company I've been to that has confluence, also has Plant UML plugin. However, it's not enabled by default for everyone. You need to create a page, select insert macro, select additional macros and somewhere under there, you insert plantuml macro. Once you do that, the PlantUML plugin is installed. You can write and render diagrams. However, everyone else will NOT see your PlantUML diagrams. They will see your code. So in order for consumers to see your diagrams, they will have to go through the same awkward process. So they will have to create a dummy page, and insert macro. PlantUML is likely disabled by default because rendering PlantUML diagrams is probably (a relatively) expensive process on the server side. It's possible that admins might not have the plugin installed for you to enable. I hope that helps.
Thanks! Great job explaining the pros and cons with these tools. I was looking to learn more about mermaid and you also got me intrigued about HackerDraw.
Nice video, and thank you. However, I notice that most of the disadvantages you note for PlantUML are actually shortcomings of the VSCode plugin. For other environments the experience here may be quite different. Perhaps you can mention that in your description, so the baseline is clear.
Thank you this was super helpful! I have been deliberating on which diagram-as-code tool to use and you helped clear it right up. I'll be using PlantUML because I work for a corporation that likes old things and may request levels of customization beyond my expectations or wishes 😀Also - I found it pretty straight-forward to do the rendering locally within VSCode.
Would love for you to revisit the topic with any new libraries you use to make architectural visualisations. I am thinking on for example "diagrams" and your take on that library...
Please! A video about packaging and virtual environment tools, how to make them work with VSCode and concerns about them stepping on (or bypassing) each other.
Hi Arjan, Do you think you'd be able to make a video on snakemake? It's a great system for developing pipelines but fairly hard to get into with the available documentation / tutorials. Big fan of your videos!
I use PlantUML with some bash scripts to compile and view the models in VIM. It kind of sucks, tbh. The compiler doesn't tell you why your code failed, only where, and there are syntactical inconsistencies: like how code blocks are sometimes defined with curly braces, keywords preceded by @, or keywords not preceded by @. It's also hard--but not impossible--to manipulate the layout of the model. The tool defiantly needs some work, but there's nothing better that I've found.
Not a good comparison, Hackerdraw is the pear among two apples here. Unfortunately, Mermaid doesn't have a diagram type for Objects.The fact that you criticize the different syntaxes (in Mermaid) for the arrows in the different diagrams and call them inconsistent shows that you don't seem to have much knowledge of the different diagram types.
💡 Get my FREE 7-step guide to help you consistently design great software: arjancodes.com/designguide.
I can't describe how much times is better to watch your videos instead of reading about the same things in books or manuals, etc. Just great!
Thanks so much Alexander, happy you find the videos helpful!
I found Mermaid thanks to you Arjan, but I eventually tried using it for a project using mypy typing and I couldn't find a way to have it show the type of non-primitive typed objects. I ended up finding PlantUML as a way to still have the benefits of Mermaid but with that additional functionality (and I was surprised at how little work was required to reformat the markdown to switch.)
You're right - they're pretty similar in terms of syntax, except PlantUML has a lot more functionality than Mermaid indeed.
About plantuml: Just run the official docker container locally and forward port 8080 to the host. Done. :)
I find that for higher level diagrams Mermaid is the way to go. Drawing tools are much more flexible, but that's also a disadvantage because we have to waste time selecting and placing the shapes, connectors, spacing, etc, all of which are unrelated to the end goal.
I only use drawing tools sparingly. By the way, you can use CSS to prettify Mermaid, but again, consumes time away from what we usually want: coding 😅
Same here. I do like Mermaid as a part of a design/feature document, but really aimed at high-level descriptions that are quicker to see in a diagram than inferring it from the text.
I like mermaid for simple tasks that I know aren't going to become any more complicated in the future, however it has a number of shortcomings that make it simply impossible to use for anything more professional.
In short, it's good for basic flowcharts, but almost every other type of diagram is broken or doesn't have pretty fundamental diagram features implemented.
Here are a few serious shortcomings I can think of off the top of my head:
1) The function duration markers on interaction diagrams are essentially broken (and I think the problem is with the way the syntax is structured so it's not even easily fixable). Go try and implement an action that happens within the time that another action is happening (e.e try making a diagram for the observer pattern). You can't do it.
2) For a number of diagrams, certain labels are required to be single words which has caused me some headaches.
3) There's no "subgraph" type feature implemented for class diagrams, (as there is for flowcharts,) so it's hard to show how a group of classes (eg a module/package) interacts with another.
4) There's no option to add code snippets within class diagrams.
excalidraw is my preference
At every company I've been to that has confluence, also has Plant UML plugin. However, it's not enabled by default for everyone. You need to create a page, select insert macro, select additional macros and somewhere under there, you insert plantuml macro. Once you do that, the PlantUML plugin is installed.
You can write and render diagrams.
However, everyone else will NOT see your PlantUML diagrams. They will see your code. So in order for consumers to see your diagrams, they will have to go through the same awkward process. So they will have to create a dummy page, and insert macro.
PlantUML is likely disabled by default because rendering PlantUML diagrams is probably (a relatively) expensive process on the server side. It's possible that admins might not have the plugin installed for you to enable.
I hope that helps.
Thanks! Great job explaining the pros and cons with these tools. I was looking to learn more about mermaid and you also got me intrigued about HackerDraw.
I'm glad you enjoyed the video!
Nice video, and thank you. However, I notice that most of the disadvantages you note for PlantUML are actually shortcomings of the VSCode plugin. For other environments the experience here may be quite different. Perhaps you can mention that in your description, so the baseline is clear.
Community version of pycharm has plant UML plug-in that does not require setting up a server.
Thank you this was super helpful! I have been deliberating on which diagram-as-code tool to use and you helped clear it right up. I'll be using PlantUML because I work for a corporation that likes old things and may request levels of customization beyond my expectations or wishes 😀Also - I found it pretty straight-forward to do the rendering locally within VSCode.
Would love for you to revisit the topic with any new libraries you use to make architectural visualisations. I am thinking on for example "diagrams" and your take on that library...
Thanks for the suggestion!
Kroki is the best!
I love their chips
Thanks for these videos! I wanted to add that you can start up a Docker container with a rendering server for Mermaid and/or PlantUML, I think.
Great tip!
Please! A video about packaging and virtual environment tools, how to make them work with VSCode and concerns about them stepping on (or bypassing) each other.
WOW PlantUML available for JSON, thanks for that news, I missed that! Great
You could always activate Ghostery to kill the ads :) Thank you for the analysis.
with plantuml you can run your own server locally. so you dont have to send data over the internet
HackerDraw looks really neat. Love it.
Thanks for the resources.
Glad you found it helpful!
Great content. Useful!!!
Glad it was helpful!
thanks for sharing 😊
You're welcome!
It's better to create CD inside visual studio if u working on it that will reduce a lot of time.
Hi Arjan, Do you think you'd be able to make a video on snakemake? It's a great system for developing pipelines but fairly hard to get into with the available documentation / tutorials. Big fan of your videos!
Very useful!
I use PlantUML with some bash scripts to compile and view the models in VIM. It kind of sucks, tbh. The compiler doesn't tell you why your code failed, only where, and there are syntactical inconsistencies: like how code blocks are sometimes defined with curly braces, keywords preceded by @, or keywords not preceded by @. It's also hard--but not impossible--to manipulate the layout of the model. The tool defiantly needs some work, but there's nothing better that I've found.
Do you know about C4 model diagrams? Does Mermaid have a way (plugin or native) to generate those diagrams?
Yeah Mermaid does have C4 model diagram but those are in experimental phase.
In my company the've PlantUML integrated with Confluence.
Thanks. Is it possible to use Material Icons instead of FA in mermaid?
Why do you not use an adblocker? there's no reason to see ads at all
Like asciidoc, I wish plantuml had more rendering support.
me too...
What do you tink of diagrams from mingrammer?
Miro is well suited for our needs
Does Miro have a textual notation for diagrams?
which tool integrates the best (easiest to use) with chatGPT?
once again great content
What about GraphViz?
GitLab support Plantuml out of the box
Mermaid!
Not a good comparison, Hackerdraw is the pear among two apples here.
Unfortunately, Mermaid doesn't have a diagram type for Objects.The fact that you criticize the different syntaxes (in Mermaid) for the arrows in the different diagrams and call them inconsistent shows that you don't seem to have much knowledge of the different diagram types.
Drawio does pretty much anything you want
Lol 😂 best joke: “corporate, for really corporate people” 👏👏
HackerDraw looks like someone just forked Excalidraw
Well if you're using macroshitCode then that's your fault.
Dot, like the dot graphics language
Wikipedia ID: DOT_(graph_description_language)
Thanks for sharing!
My first thought, Why not just use graphviz...
@@ArjanCodes :)
@@90hijacked PlantUML is built on top of graphviz & just adds markup syntax for UML.