The choice is usually made by whoever draws the first diagram, and then everybody lives with it for years. It is worth five minutes of thought, and the deciding question is not which tool is best but who will edit this thing next. Short answer. A visual editor such as draw.io for diagrams that non-engineers maintain. Mermaid or PlantUML when the diagram belongs with the code and should be reviewed like code. An attached SVG when the picture comes from a design tool and you need it to look exactly right. A screenshot when the diagram will genuinely never change again. The four options A diagramming app inside Confluence draw.io is the common choice, and it is free for small teams. The diagram is created and edited inside the page, links on shapes work, and anyone who can use a mouse can maintain it. This is the default answer for architecture maps, process flows and floor plans that live in the documentation and get corrected by whoever notices the mistake. The cost is lock-in of a mild kind: the diagram lives in the app's format, and moving to something else later means exporting and redrawing. Mermaid or PlantUML: diagrams as text Here the diagram is source code — a few lines describing nodes and arrows, rendered into a picture. The appeal is real: text goes into version control, diffs are readable, and a diagram can be generated by a script from the system it describes. Two things to know before choosing this. Confluence Cloud does not render Mermaid natively, so you need an app for it, and several of them exist including free ones. And the editing audience narrows sharply: a technical writer will not touch a diagram that has to be edited as syntax, so the diagram becomes the property of the engineers, whether you intended that or not. An SVG made somewhere else The diagram comes from Figma, Illustrator, Inkscape, Visio or an architecture tool, and lands on the page as an attachment. It looks exactly as designed, which is why people do it. The catch is documented and unavoidable: Confluence Cloud flattens an attached SVG into a raster image before showing it, because SVG files can carry scripts. Links inside the diagram stop working, hover states disappear, and the text inside becomes pixels that search cannot see. We wrote about why this happens and what to do separately. A screenshot Unfashionable, and sometimes correct. For a diagram that documents a moment — an incident timeline, the state of a system before a migration — a picture is the honest format, because there is nothing to keep up to date. It becomes a problem the moment the thing it shows starts changing. Then the source file is on somebody's laptop, that somebody has left, and the picture on the page is quietly wrong. Side by side Visual editor Mermaid / PlantUML Attached SVG Screenshot Who can edit Anyone People comfortable with syntax Whoever owns the source file Nobody Links on shapes Work Limited Lost on display None Searchable text Usually Yes, the source is text No, it becomes pixels No Review like code No Yes, that is the point No No Looks exactly as designed Close enough The renderer decides Yes Yes Needs an app Yes Yes No, but interactivity needs one No How to actually choose Ask three questions in this order, and the answer usually falls out. Who edits it next year? If the honest answer is "a writer, a manager, whoever spots the error", pick a visual editor. Text-based diagrams look elegant right up to the moment a non-engineer has to change one box. Does it change with the system? If the diagram describes something that evolves and can be generated from it, text wins. A picture of an architecture is out of date the week it is drawn; a generated one is not. Do people need to click through it? A map that exists to help people navigate documentation is worth nothing if the boxes are not links. That rules out screenshots entirely, and it is the reason an attached SVG needs help. One more thing worth checking before you commit: whether the app you are about to standardise on is still maintained. Several diagram apps for Confluence have been abandoned over the last few years, and their users found out the hard way. Our notes on the abandoned Mermaid apps and the same for PlantUML cover how to tell. Disclosure: I build Clickable SVG, which covers the third case — an SVG that already exists and needs its links working inside Confluence, plus rendering for Mermaid and PlantUML source. If your diagram does not exist yet, draw it in a visual editor and you will not need my app at all. That is the honest recommendation and it costs me nothing to make. Frequently asked Can we mix approaches? Most teams end up doing so, and that is fine as long as it is by decision rather than by accident. The failure mode is four approaches in one space because four people each picked their favourite. What about diagrams generated from code? That is the strongest case for the text-based route: the diagram is produced by the build, so it cannot drift from reality. Worth the syntax cost when the system changes weekly. Does exporting to PDF keep the diagrams? Rendered diagrams appear in exports as images. Interactive behaviour, including links, does not survive a PDF, which is a good reason not to make navigation depend on a document that people print.