Why this session exists
A data platform is maybe 40% system and 60% coordination: when things ship, what happened before you joined, who's doing what this sprint, how releases flow, how stakeholders actually experience your work, and what the domain even contains. All of that coordination is usually trapped in slide decks and tribal memory. Mermaid has a diagram type for each of these - smaller grammars than flowcharts, learnable in minutes each. This is a breadth session: six types, one honest Nova example apiece. Depth comes from using the two or three YOUR week needs.
Gantt - the roadmap 6 min live
The gantt is the diagram executives already know how to read - which makes it the highest-leverage type in this session. Mermaid's version is dates-in, bars-out: you declare tasks and dependencies, it computes the calendar.
LiveAnatomy: dateFormat, sections, tasks, after4 min▶
Four header lines set the stage, then every task is one line: Name : tags, id, start, duration. The magic word is after - chain tasks by id instead of hard-coding dates, and the whole plan reflows when one thing slips.
gantt
title Nova Q3 delivery plan
dateFormat YYYY-MM-DD
axisFormat %b %d
excludes weekends
section Foundations
Ingestion v2 rollout : done, ing2, 2026-07-06, 10d
Schema registry : active, reg, after ing2, 8d
section Quality
Quality gate library : crit, gates, after reg, 10d
Freshness SLAs : slas, after gates, 5d
section Serving
Feature store MVP : feat, after gates, 12d
Exec dashboards : dash, after slas, 8d
Q3 review : milestone, rev, 2026-09-28, 0d
- The task line, decoded: optional status tags first (
done,active,crit,milestone), then an id you'll reference, then a start (a date ORafter someId), then a duration (10d,3w) - or an end date. after ing2beats 2026-07-20: hard-coded dates go stale the first time anything slips; dependencies reflow automatically. Date only the true anchors.critmarks the critical path in red - the chain where a slip moves the end date. One glance answers "what must not slip?"milestone+0drenders a diamond - a point in time, not a bar. Reviews, launches, deadlines.excludes weekendsstops bars from pretending your team works Saturdays. You can exclude specific dates too - release freezes, holidays.
Self-studyLiving roadmaps - the workflow that makes gantt worth it1 min read▶
A gantt in a slide deck is dead on arrival; a gantt in the repo README is a living document. The workflow that works: statuses updated in the same PR that finishes the work (active becomes done - a one-word diff), plan changes reviewed like code changes, and the diagram is never "the old version" because there is only one version. For long programs, look up tickInterval and compact display mode in the docs - the fine-tuning layer we're leaving for your rainy day.
Timeline + gitGraph - history 7 min live
Two ways to draw the past: the timeline tells the story in eras for humans, the gitGraph tells it in branches for engineers. Both answer "how did we get here?" - the question every new joiner asks first.
LiveTimeline - eras and events3 min▶
The simplest grammar of the day: period : event, one per line, extra events on continuation lines starting with a colon. Group periods into named section eras and the diagram color-bands them. Order matters - first line renders leftmost.
timeline
title Nova platform history
section Scrappy era
2023 : CSV exports by hand
: first cron job
section Foundation era
2024 : warehouse launched
: quality checks v1
section Platform era
2025 : feature store pilot
: exec dashboards
2026 : Nova named + funded
Periods are just labels - years here, but "Q1", "v2 launch", or "Before the incident" work exactly the same. The section names carry the narrative: notice how "Scrappy era" to "Platform era" tells the maturity story before a single event is read.
LivegitGraph - the release flow4 min▶
gitGraph draws commit history: commit, branch, checkout, merge read exactly like the git commands they mirror. Its killer use isn't documenting real history - git already stores that - it's explaining your branching CONVENTION as a picture new engineers absorb in seconds.
gitGraph commit id: "init pipelines" branch develop commit id: "quality gates" commit id: "fix null rates" checkout main merge develop tag: "v1.4" branch hotfix commit id: "patch crm parser" checkout main merge hotfix tag: "v1.4.1"
branchcreates AND switches - commits after it land on the new branch until youcheckoutelsewhere (switchworks too).- Name your commits:
commit id: "quality gates"beats auto-generated hashes for teaching diagrams;tag: "v1.4"hangs release labels on merges. - Keep it idealized. Eight to twelve commits showing the CONVENTION - the real repo has ten thousand commits and no lesson in them.
The most-viewed page in many platform teams' docs is "how we release" - and the teams that draw it as a gitGraph stop answering the same three questions in every onboarding: where do features branch from, what gets tagged, and where do hotfixes go. Twelve lines of text, asked-and-answered forever.
Kanban + journey + mindmap - work and minds 8 min live
Three quick grammars to finish the set: the backlog as it stands, the experience as it feels, and the domain as you think it. Each is under ten lines to learn.
LiveKanban - the backlog snapshot3 min▶
Columns are top-level entries, cards indent beneath them, and metadata rides in an @{ } block: who owns it, which ticket, what priority. Perfect for sprint snapshots in a doc or an incident work-tracking page - places a full Jira board is overkill.
kanban
todo[To do]
t1[Document event schema]@{ assigned: "Maya", ticket: "NOVA-121", priority: "High" }
t2[Backfill June orders]@{ ticket: "NOVA-118" }
doing[In progress]
t3[Freshness alerts]@{ assigned: "Ade", priority: "Very High" }
review[In review]
t4[CRM dedupe rule]@{ assigned: "Priya", ticket: "NOVA-115" }
done[Done]
t5[Warehouse cost report]
Priority accepts "Very High", "High", "Low", "Very Low". All metadata is optional - a bare t5[Warehouse cost report] is a perfectly good card. Moving work = moving one line between columns, which means your standup snapshot diffs in git.
LiveUser journey - experience with honest scores3 min▶
The journey diagram walks through an experience task by task, scoring each step 1-5 - and renders a face per step. Syntax: Task name: score: actor under section headers. The faces are the point: a row of frowns is an argument no metrics dashboard makes as fast.
journey
title An analyst asks a data question
section Finding the data
Search the catalog: 3: Analyst
Ask in the data channel: 2: Analyst, Data eng
section Getting an answer
Write the query: 4: Analyst
Wait for the backfill: 1: Analyst, Data eng
section Sharing it
Build the chart: 5: Analyst
Present to stakeholders: 4: Analyst
Scores mean SATISFACTION of the actors doing the step: 1 is miserable, 5 is delighted - not priority, not effort. Multiple actors comma-separate and each gets a colored track. The discipline that makes this diagram valuable: score how it actually feels today, not how the process doc says it should feel.
LiveMindmap - the shape of your thinking2 min▶
Mindmaps are pure indentation: a root, then children nested by indent depth - and only RELATIVE indentation matters. Wrap node text in brackets to pick shapes: ((circle)) for the root, [square], (rounded), {{hexagon}} for emphasis tiers.
mindmap
root((Nova))
Ingestion
Event stream
CRM drop
Quality
Gates
Freshness SLAs
Serving
{{Warehouse}}
Dashboards
ML features
People
[Runbooks]
(Office hours)
Best uses in a data team: scoping a new domain before anyone argues about tables, structuring a doc before writing it, and capability maps like this one. It's the five-minute diagram - when thinking is still soft, the mindmap holds it without forcing arrows and cardinalities on it too early.
Self-studyChoosing between the six - the chooser table2 min read▶
Six types is a toolbox, not a to-do list. Match the question in the room to the grammar:
| The question in the room | Reach for | Because |
|---|---|---|
| "When will it ship, and what must not slip?" | gantt | dependencies + crit path compute the answer |
| "How did we get here?" | timeline | eras and events tell a story left to right |
| "How do we branch and release?" | gitGraph | the convention, drawn in the team's own vocabulary |
| "Who's doing what right now?" | kanban | columns + owner/ticket metadata, diffable snapshots |
| "How painful is this for the people in it?" | journey | scored steps make friction visible as faces |
| "What does this domain even contain?" | mindmap | structure without commitment - ideal while thinking is soft |
Rule of thumb: pick by the QUESTION, not by which syntax you like. If the room is asking two questions, that's two diagrams - each small, rather than one overloaded.
Build the Nova Q3 gantt ★ 8 min · follow along
We rebuild Part 1's roadmap from an empty editor - the finicky one, done slowly, so the comma grammar sticks.
In mermaid.live, lay the header: gantt, title Nova Q3 delivery plan, dateFormat YYYY-MM-DD, excludes weekends. Empty chart, no errors.
Add section Foundations and its first task with a real date: Ingestion v2 rollout : done, ing2, 2026-07-06, 10d. One bar appears, styled as finished.
Chain the second task with after: Schema registry : active, reg, after ing2, 8d. No date typed - the bar computes its own start.
Add section Quality with the crit task: Quality gate library : crit, gates, after reg, 10d. Red bar = the chain that decides the end date.
Add section Serving with two parallel chains (after gates, after slas) and close with the diamond: Q3 review : milestone, rev, 2026-09-28, 0d.
Now the payoff: change ing2's duration from 10d to 15d and watch the whole dependent plan reflow. That's the slide-deck gantt's funeral - re-plan by editing one number.
Your release flow as gitGraph ★ 5 min · build your own
Draw how YOUR team ships - the idealized convention, not the messy reality. If you can't draw it in twelve commits, that's information too.
Start with gitGraph and two or three commit id: "..." lines on main - name them after real kinds of work, not "commit 1".
Model your feature flow: branch develop (or feature branches, if that's your convention), a couple of commits, checkout main, merge develop.
Hang a release on the merge: merge develop tag: "v1.4". If your team tags elsewhere, draw THAT - the diagram documents your convention, not the textbook's.
Add the exception path everyone asks about: a hotfix branch from main, one commit, merged back with a patch tag.
Gut check: does the drawing match what actually happened last release? If not, you've discovered the gap between the convention and the practice - worth a team conversation either way.
Map your domain, then walk a mile in a stakeholder's journey ★ 5 min · build your own
Two soft diagrams, back to back: your domain as a mindmap, then one recurring stakeholder experience as a journey - with scores you'd defend to their face.
Mindmap first: root((your domain)), then 3-5 branches, each 2-3 children deep. Set a three-minute timer - the mindmap is a thinking speed tool, and overworking it defeats the point.
Promote with shapes: {{hexagon}} the branch that matters most this quarter, [square] the ones that are stable and boring. Shape = emphasis, even here.
Now the journey: pick one experience that recurs - "stakeholder requests a new dashboard" is the classic. Two or three sections, five to seven tasks.
Score each step honestly as the STAKEHOLDER feels it, 1-5. The step you're tempted to score 3 "to be fair to the team" - that's usually a 2, and usually the finding.
Look at the lowest face on the render. That step is a roadmap candidate - and now you have the picture that argues for it in the next planning meeting.
A data team journey-mapped "requesting a new metric" and scored the waiting step a 1. The map went into the quarterly review; the self-serve metrics catalog it justified cut that wait from days to minutes. The diagram didn't fix anything - it made the pain undeniable enough to fund the fix.
Try it yourself - this week ◐ 30-45 min total
- Take the real roadmap living in your spreadsheet or deck and rebuild it as a gantt with
afterdependencies and onecritchain. Put it where the project is discussed and update statuses in PRs. - Write your team's or platform's timeline in three named eras. Show it to the longest-tenured teammate and let them correct the history - that correction is the real documentation happening.
- Commit your Demo 2 gitGraph to the repo's CONTRIBUTING or release doc. Next onboarding, send the link instead of the speech.
- Journey-map one recurring stakeholder experience you own, honest scores. Bring the lowest-scored step to your next planning conversation.
- Chooser drill: for the last five diagrams-shaped questions that came up at work, name which of the six types you'd reach for - out loud, using the chooser table's question column.
- Bring to Session 6: your messiest diagram from any session so far. The pro layer - themes, config, CI rendering, ELK layout - is how we make it presentation-grade.
Official docs covered
This session teaches the working content of six syntax pages of the official docs at mermaid.js.org (mermaid 11.x) - breadth-first, each to daily-driver depth.
Three questions before you go 🎯 ◐ 90 seconds
1 · In a gantt, Schema registry : reg, after ing2, 8d means the task...
after chains the start to the other task's END. That reflow is the whole reason to prefer dependencies over hard-coded dates.
2 · In a user journey, the score in Wait for the backfill: 1: Analyst measures...
Journey scores are satisfaction, rendered as faces. Low faces make friction visible - which is exactly why the scores must be honest.
3 · How does a mindmap know which node is whose child?
Pure indentation, and only RELATIVE depth matters. No arrows, no ids - which is why it's the fastest diagram in the toolbox.