2025-05-16
Diagramming: Markup vs By Hand
When creating diagrams, there are two main approaches: describe them in text/markup (great for automation, version control, and AI generation) or draw them by hand (great for quick sketches and whiteboarding).
Which diagram tool should I use?
- Graphviz — best when diagrams are generated programmatically (dependency graphs, decision trees, automation output) using the DOT language.
- MermaidJS — best for handwritten diagrams in docs and developer sites: flowcharts, sequence, class, and state diagrams that live next to your Markdown.
- PlantUML — best for rich UML: sequence, class, use case, activity, and component diagrams.
- Excalidraw — best for freehand sketching and whiteboarding when you want a quick, hand-drawn look rather than generated output.
1. Markup-based Diagrams
Markup-based tools let you describe diagrams using text. This is great for automation, version control, and reproducibility. Two popular markup tools are:
- Graphviz: Easier to generate programmatically, widely used in scripts and automation. Its syntax is simple and well-suited for code generation. Try it in the Graphviz Playground.
- MermaidJS: Designed to be easy to handcraft, and looks better on the web. Mermaid is great for documentation and developer websites. Try it in the MermaidJS Playground.
- PlantUML: A rich UML-focused syntax for sequence, class, use case, activity, and component diagrams. Try it in the PlantUML Playground.
You can see a side-by-side comparison of Graphviz and MermaidJS to help you choose the right tool for your needs.
2. By Hand (Visual Drawing)
Sometimes you want to sketch diagrams by hand, drag and drop shapes, or collaborate visually. For this, try Excalidraw, a freehand drawing tool for quick sketches and collaborative whiteboarding.
