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.
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.
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...
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.
