标签：#diagrams

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