Mermaid: Diagrams as Shared Language for Humans and Agents

Here’s the thing. A lot of teams are moving towards simplicity. Fewer tools, less friction, more reuse. More importantly, we are moving towards work products that machines can read and machines can understand, without losing the human ability to look at something and go, “ah, I get it”.

Mermaid is a great example of that.

Instead of drawing diagrams in a separate tool, you write a small bit of text inside your Markdown and the tooling renders it into a diagram. That means your meeting notes, your runbooks, your README files, your decision logs, they can contain both:

• A diagram humans can scan quickly
• The underlying structure that systems (including AI agents) can parse, compare, and reason over

That is the bridge I care about. Humans need to visualise. Machines need the data. When both get what they need from the same artefact, things get calmer.

What Mermaid is (in plain English)

Mermaid is diagrams as text. You write something like a flowchart in a code block, and the renderer turns it into a visual diagram.

GitHub put it neatly:

"Mermaid is a Markdown-inspired tool that renders text into diagrams. For example, Mermaid can render flow charts, sequence diagrams, pie charts and more."
Source: GitHub Docs, https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams 

If you want to go deeper on syntax, the official reference is worth bookmarking.
Source: https://mermaid.js.org/intro/syntax-reference.html 

The pattern I want you to adopt: meeting to maintainable artefact

Most diagrams rot for one boring reason. They are not maintained because they are not easy to maintain.

A slide gets exported. A screenshot goes in a wiki. Someone owns a file on their laptop. Nobody wants to touch it.

So, here’s the actionable pattern, and it works whether you are a startup or a big org.

The Meeting to Mermaid pattern (5 steps)

1. Capture the conversation

• While someone explains the process, capture the nodes and the flow.
• Keep it rough. Clarity first, perfection later.

2. Turn it into Mermaid text

• Write the Mermaid code in the notes as you go.
• If you use an AI assistant to draft it, treat that draft like any other draft. Review it.

3. Confirm it with humans

• Read it back to the room.
• Ask one question: “Is this what we do, or what we wish we did?”

4. Store it where it can be maintained

• Put it in the repo next to the docs and runbooks.
• Now it can be reviewed, updated, and versioned.

5. Let agents consume the structure

• Humans look at the picture.
• Systems read the structure.

This is why I keep calling Mermaid a shared language. It is one artefact serving two audiences.

Canonical describe the maintainability win in a way I think most teams feel in their bones:

"Creating diagrams as code solves this by keeping them alongside the software source, making updates and reviews simpler."
Source: Documentation starter pack, https://canonical-starter-pack.readthedocs-hosted.com/dev/how-to/diagrams-as-code-mermaid/ 

A minimal Mermaid example you can copy

Example (flowchart), paste this into a Markdown file and render it where Mermaid is supported:

flowchart TD
  A[Meeting conversation] --> B[Draft Mermaid in Markdown]
  B --> C[Team confirms meaning]
  C --> D[Commit to repo]
  D --> E[Humans see diagram]
  D --> F[AI reads structure]

That is the whole point. You keep the visual, and you keep the data.

If you want more flowchart options (decision diamonds, labels, subgraphs), Mermaid Chart’s flowchart syntax guide is a practical reference.
Source: https://mermaid.ai/open-source/syntax/flowchart.html 

How to keep Mermaid diagrams maintainable (and safe)

This is the part people skip, then complain later.

Maintainability guardrails

• Keep diagrams close to the work
• Put the Mermaid next to the runbook, system doc, or process doc it describes.
• If the process changes, the diagram changes in the same pull request.

• Review diagrams like you review documentation
• Ask: does this reflect reality?
• Ask: is it understandable by someone new?

• Prefer small diagrams
• One diagram per concept is usually enough.
• Big diagrams become posters, then they become ignored.

Safety and confidentiality guardrails

• Do not put secrets in diagrams
• No tokens, credentials, private URLs, customer identifiers, incident details that should stay private.
• Assume diagrams travel
• If it is in a repo, it will be copied, quoted, screenshotted, forwarded.
• Design for that.

Where this shows up on GitHub (and why that matters for teams)

If you are already collaborating in GitHub, Mermaid becomes a natural part of the workflow. GitHub’s own docs highlight that diagrams can live where your conversations and reviews already happen:

"You can create diagrams in Markdown using four different syntaxes: mermaid, geoJSON, topoJSON, and ASCII STL. Diagram rendering is available in GitHub Issues, GitHub Discussions, pull requests, wikis, and Markdown files."
Source: GitHub Docs, https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams 

That matters because it turns diagrams from “a thing someone made” into “a thing the team maintains”.

Three practical use cases you can try immediately

1. Process map that stops drifting

• Onboarding, approvals, handovers, escalation paths.
• Put the flowchart in the same place as the written steps.

2. Incident runbook clarity

• A small decision flow that answers “if X, then do Y”.
• Keep it close to the runbook so it is updated when the runbook is updated.

3. Decision flow for leadership

• Escalation criteria, go or no-go checks, what triggers a pause.
• A diagram forces you to be explicit about decision points.

A small experiment for this week (keep it simple)

• Pick one recurring meeting where people explain a process.
• Capture the process as Mermaid text while the conversation is happening.
• Read it back for confirmation.
• Put it somewhere maintainable (ideally in a repo, alongside the docs).
• Next week, update it when reality changes.

Build small, learn fast. The goal is not “beautiful diagrams”. The goal is shared understanding that can be maintained.

Links

• Diagram Syntax | Mermaid: https://mermaid.js.org/intro/syntax-reference.html 
• Flowcharts Syntax, Mermaid Chart: https://mermaid.ai/open-source/syntax/flowchart.html 
• Creating Mermaid diagrams, GitHub Docs: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams 
• Create diagrams as code using Mermaid, Documentation starter pack: https://canonical-starter-pack.readthedocs-hosted.com/dev/how-to/diagrams-as-code-mermaid/ 
• How to Create Diagrams as Code with Mermaid, GitHub, and VS Code, freeCodeCamp: https://www.freecodecamp.org/news/diagrams-as-code-with-mermaid-github-and-vs-code/ 

Quotes

"Mermaid is a Markdown-inspired tool that renders text into diagrams. For example, Mermaid can render flow charts, sequence diagrams, pie charts and more."
Source: GitHub Docs, https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams 

"You can create diagrams in Markdown using four different syntaxes: mermaid, geoJSON, topoJSON, and ASCII STL. Diagram rendering is available in GitHub Issues, GitHub Discussions, pull requests, wikis, and Markdown files."
Source: GitHub Docs, https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams 

"Creating diagrams as code solves this by keeping them alongside the software source, making updates and reviews simpler."
Source: Documentation starter pack, https://canonical-starter-pack.readthedocs-hosted.com/dev/how-to/diagrams-as-code-mermaid/ 

#Educate #Mermaid #Markdown #DiagramsAsCode #Documentation #AgenticSystems #HumanPlusAI