Most diagrams are drawn, which is why most diagrams are wrong. There is another way: describe the diagram in a few lines of text and let software draw it, so keeping it current is an edit rather than a job. This walks you through Mermaid, the small language that does it, with a working editor you can type into. About fifteen minutes, and you need nothing installed.
Myth we'll unpick: "a diagram is a picture you draw"
Some are. But the ones that describe a living system are better thought of as a view onto something else, and that changes what you should make them out of.
Everyone has met this diagram
There is a process map in a shared folder somewhere with a filename ending _FINAL_v3.vsdx. Somebody spent a good afternoon on it. It was accurate for about five weeks. Nobody has updated it since, because updating it means finding whoever has the licence, opening the file, moving fourteen boxes and re-exporting the image that got pasted into the induction pack. So it sits there, quietly wrong, being shown to new starters.
The problem is not that the diagram was drawn badly. It is that the cost of a small correction was too high, so small corrections never happened.
The life of a drawn diagram
Week oneAccurate, admired, pinned to the wall. Somebody says "we should keep this updated".
Month twoA step changes. Updating it is a twenty-minute job in an application only two people have. It goes on a list.
Month sixThree more changes. The exported PNG in the handbook is now the version people actually see, and it is two revisions behind the source file.
Year twoNobody trusts it. Somebody starts a new one from scratch, and the cycle begins again.
The failure is in the format, not the effort. So change the format.
What if the diagram were text?
If the source of a diagram is a few lines of plain text, then correcting it is editing a line. It can live in the same file as the documentation it belongs to, travel through the same version history as the code it describes, and be reviewed the way any other change is reviewed. You stop maintaining a picture and start maintaining a description.
This is what Mermaid does. It is a small text language; other software reads it and draws the picture.
Module 02
Ten minutes of syntax
There is much more to Mermaid than this, but the flowchart subset below covers most of what anyone actually draws at work. Two ideas: nodes have shapes, and arrows join them.
The shape is in the brackets
Pick a syntax to see what it draws
Arrows, and what goes on them
An arrow is --> and a plain line is ---. To put a word on the arrow, wrap it in pipes: C -->|Yes| D. And once a node has been given its label, you can refer to it by its short name alone for the rest of the diagram, which is why a loop back is just one more line.
The first line of the diagram sets the direction. flowchart TD runs top down; flowchart LR runs left to right. That single word is often the difference between a diagram that fits on the page and one that does not.
Type something and watch it draw
You write this
Software draws this
An honest note about that editor
The renderer on the previous beat is a small one written for this walkthrough, handling the flowchart subset taught here so the page stays self-contained and works offline. Real Mermaid does a great deal more: sequence diagrams, entity relationships, Gantt charts, state machines, mind maps, and much better layout than this. Treat what you just used as the training wheels.
The next module covers where the real one lives.
Module 03
Where it renders, and who writes it
Mermaid is not an application you install. It is text that other tools already know how to draw, which is the whole point of it.
Four places it already works
You do not have to write it yourself
Mermaid is text, so an assistant can produce it. Paste your process into Copilot, or any other assistant, and ask for a Mermaid flowchart of these steps; you will get something close, which you then correct. This is the practical reason to learn the syntax even if you never write one from scratch: you need to be able to read what comes back.
Two cautions. Assistants sometimes emit syntax from a different version and it will simply refuse to render; paste it into the live editor and it will name the offending line. And they invent plausible-sounding steps, so check the diagram against the actual process rather than against how tidy it looks.
Now you read it
Everything you need is in the two modules you have just done. What does this draw?
flowchart LR
A[Form submitted] --> B{Spam check}
B -->|Clean| C[(Store)]
B -->|Suspect| D[Quarantine]
A left-to-right chart: a rectangle, an arrow into a diamond, and two labelled arrows out of it; one to a cylinder, one to a rectangle.The cylinder is the giveaway that Store is a database rather than a step. Shape carries meaning; that is why choosing brackets carelessly makes a diagram lie.
This one has a mistake in it. The author wanted the rejected path to go back to the check.
flowchart TD
A[Draft] --> B{Approved?}
B -->|Yes| C([Published])
B -->|No| D[Revise]
There is no line back. Add D --> B and the loop closes.Missing return paths are the most common error in a hand-written flowchart, in any tool. Reading the text makes it obvious in a way that staring at the picture does not.
Module 04
Write it, or draw it
This is not an argument that Mermaid replaces a drawing tool. They answer different questions, and knowing which is which is the skill worth taking away.
Six honest differences
Drawing toolWritten diagram
Layout controlComplete. Every shape exactly where you want it.None. The software decides, and sometimes decides badly.
Cost of a changeOpen the file, move things, re-export.Edit a line.
Who can edit itWhoever holds a licence.Anyone with a text editor.
Version historyA binary file; you can see that it changed, not what changed.A readable difference, line by line.
Where it livesA separate file beside the document.Inside the document, the notes, or the repository.
How it looksAs polished as you are willing to make it.Consistent, plain, and not yours to fuss over.
Notice that the drawing tool wins on presentation and the written diagram wins on maintenance.
Why this matters
Reach for a drawing tool when the diagram is the deliverable: a tender, a report, a client hand-over, anything where the layout is part of the argument. Reach for a written diagram when the picture describes something that changes and needs to stay true. The second kind is far more common than the first, and it is the kind almost everybody has been making the wrong way.
One more thing worth noticing. Generating a diagram from a table in a drawing tool, and generating one from text in an editor, are the same idea: the source is what you maintain, and the picture is an output. That is the difference between a diagram you own and a diagram that owns you.
Sources used. Mermaid documentation and syntax reference, mermaid.js.org, version 11.16.0 as displayed 4 August 2026; no page date shown. Mermaid Live Editor, mermaid.live, checked 4 August 2026. GitHub Docs, "Creating diagrams", docs.github.com, checked 4 August 2026; no publication date shown. The renderer used in module 02 was written for this page and handles a subset of the flowchart syntax only.