I work as a system analyst, and when people ask what I love most about my job, I don't even need to think about it: building diagrams, obviously. For me, it's far more than just a work tool. It's more like a genuine professional hobby — bringing order to flows and scenarios, hunting for the right color palette and the perfect geometry... Mmm, I really do love it!So even now, in the age of AI, when neural networks are gradually being handed every routine task — right down to choosing what to have for lunch — I'm still very reluctant to let them build diagrams for me. I love the process itself: I want to savor every step of it, gradually sinking into all the nuances of whatever task is at hand.Of course, I'm not planning to heroically resist progress and manually align every rectangle for the rest of my life. Over the past few years I've been watching, with real interest, the rise of the diagram-as-code approach and the tools that support it. In my view, they noticeably simplify creating, editing, and maintaining diagrams: instead of endlessly dragging elements around with a mouse, you get code that can be quickly fixed, compared, and stored right alongside the rest of the documentation.This approach really shines when working with UML Sequence diagrams — arguably one of the most in-demand genres in our analytical craft. And no wonder: interaction sequences change all the time and rebuilding half a diagram with the almighty drag-and-drop is a rather... acquired taste.Over the past couple of years, I've had to decide, more than once, which tool to pick for a project: Mermaid or PlantUML. Personally, I feel their rivalry has already earned its own story arc in the next Mortal Kombat installment. But in actual project work, PlantUML has come out on top for me, round after round. Tasks changed, teams changed, technical constraints changed, but my choice stayed the same, round after round, with not much suspense left for the finale.Sometimes, that choice wasn't entirely rational: a project might already have ready-made infrastructure for fast Mermaid rendering, and I'd still keep insisting on my way. Apparently, loyalty to a professional hobby can occasionally make an analyst resist even perfectly reasonable project compromises.But my comparison criterion is quite specific. What matters to me isn't just a diagram's functional content, but also how visually clear it is to every stakeholder — from developers to people looking at UML for the first time and already mildly regretting it. So, from here on I won't compare the tools by feature count or number of integrations, but by how easily each one lets you make a UML Sequence diagram visually unambiguous. And I'll walk through several reasons why I keep choosing the rather old-fashioned-looking PlantUML over the trendy, accessible Mermaid.Well then, the fighters are chosen... Get over here!Fine-Tuning Vertical SpacingOne of Mermaid's notable issues, still unresolved, is the lack of local control over vertical spacing: you can't just add a bit of breathing room around one specific element without affecting the entire rest of the diagram. For message labels, there's a workaround using , which can push a label down, but it won't help you add space between other objects. There's also a global workaround — the boxMargin parameter — but it increases the spacing between absolutely every element, no exceptions.As a result, a message label ends up as far from its arrow as, say, a grouping frame is from a neighboring arrow — even though visually these are completely different relationships. The choice you're left with isn't exactly generous: either elements stay squished together, and the diagram suffers in terms of visual accessibility, or you bolt on workarounds and unnecessarily stretch it out vertically.In PlantUML, for cases like this, you can add local vertical spacing using ||| exactly where you need it, without restructuring the whole diagram. In other words, Mermaid lets you increase the distance, but it still can't tell the renderer exactly between which elements that distance is needed. And that's less a matter of aesthetics than a matter of managing the reader's attention.Visual CustomizationYou'd think there's no real challenge here: pick a global theme for all the elements, and everything already looks modern and readable. The trouble starts when you want targeted customization rather than a global one. For example, on my diagrams, I use a light scarlet shade to highlight error handling: it immediately helps distinguish the main scenario from the moment things stopped going according to plan.In Mermaid, I can't control individual element colors that freely. For the same reason, you can't visually separate a main activation box from a nested one: from a distance, they'll blend together, which again, hurts the diagram's visual accessibility, even though technically no information gets lost. PlantUML gives you more freedom here: color can be applied selectively, as part of the diagram's visual semantics, not just as an overall styling theme.That said, limited customization is only half the problem. Even if you make peace with the overall color scheme, there are still small rendering quirks: activation boxes stick to the borders of other shapes, and labels for centered self-calls end up centered relative to the participant's lifeline instead of the arrow. It doesn't look especially tidy, though the diagram still stays usable for work.Things get a lot more entertaining once you start experimenting with theme configuration: one careless move, and everything you carefully “coded” suddenly stops looking the way you intended — Mermaid switches on the most acid-trip theme available. To this day, I have no idea exactly how I triggered that special effect... Since then I've washed my hands of it and stopped looking for any visual workarounds altogether.Nested Activations Gone WrongSpeaking of nested activations. For an analyst, this isn't some decorative flourish but a genuinely useful abstraction: we don't always have access to full information about what's going on under a product's hood. In these cases, self-activations let you neatly collapse the unknown internal machinery into a single step, without cluttering the diagram with guesswork while keeping detail exactly where it matters for key scenarios.But trying to depict a call like that in Mermaid quickly turns into a bit of a quest:Round one. If you add a simple self-call while an activation box is already open, the existing box mysteriously shifts below the arrow: no new box gets created, the old one just changes position, and the arrow doesn't even land inside the original activation. It's a little cringe, honestly.Round two. We don't give up, and on the next line we deactivate the nested box that Mermaid apparently hadn't created yet — and it suddenly appears. Hooray, the magic worked! Except the arrows still stick into the original activation box they were called from, not the nested box they were actually calling.The result leaves plenty of room for interpretation, which is especially ironic, given that a diagram's whole job is to eliminate exactly that kind of ambiguity. In PlantUML, the same scenario renders more predictably: the nested activation stays nested, and the arrows visually connect to the exact execution level they belong to.A Mermaid Hater?With all that said, I can't really call myself a die-hard Mermaid hater: roughly every six to eight months I give the tool a fresh test drive and check what's changed. And there really has been progress: for instance, Mermaid now lets you control message label alignment. And the Mermaid Live Editor has become a lot more stable over the past couple of years, too.During my most recent check, Deep Search confirmed that at least some of the issues described here have already been logged and are slated for a fix. So there's hope, there's a roadmap, and all that's left is to wait it out. What's more, you can't take away Mermaid's biggest strengths: it really is simple, accessible, and hugely popular. The tool has firmly claimed its niche — automatic rendering in ChatGPT? Sure. Built-in diagram support in Azure DevOps Wiki? Sure. And that's just the tip of the iceberg.But despite all those upsides, I'm still an evangelist for one simple principle: a diagram should remove communication friction, not create new friction. That's exactly why, for UML Sequence diagrams, I value PlantUML's predictability and controllability — the ability to locally adjust spacing, visually separate scenarios, and clearly show nested activations. Given all the technical constraints, diagrams built with it come out, in my opinion, noticeably neater and clearer. Which means they make communication on integration projects simpler and more transparent.One Last AsideThat said, all of this applies primarily to UML Sequence diagrams. Outside that genre, PlantUML's advantage is far less obvious. So yes, for the record, the PlantUML developers did not pay me for this post: try “coding” a few other types of UML diagrams, and the balance of power restores itself pretty quickly. In that territory, Mermaid and PlantUML are a fairly even match and not always in a good way. The rendering results almost always end up far from ideal, and far from anything I'd be comfortable showing my colleagues at work.That said, there's an argument that a third force in the diagram-as-code market — a tool called D2 — could eventually give both established leaders a run for their money. Its design is pleasant, and the default auto-layout works surprisingly sensibly, almost as if the tool genuinely guesses what the user wanted. For now, though, D2 remains more of an insider's tool: interesting, promising, but fairly niche. And apparently, knowing how to actually embed these diagrams in Confluence is knowledge reserved for a select few initiates.