MermaidTeamWorkflowsCollaboration

Build team collaboration workflows with Mermaid

June 17, 20266 min readThe MermaidCreator team

When a team's workflow lives only in Slack conversations and wiki pages, new members take weeks to understand how work moves. Mermaid diagrams fix that — they're plain text, live in your repository, and everyone can read them. This guide shows how to use Mermaid to document the real workflows that drive team collaboration.

Why diagram team workflows

Unwritten workflows create invisible friction. A developer doesn't know who approves database changes. A designer doesn't know when to hand off to QA. A product manager assumes a feature is ready but engineering is still blocked on a dependency.

Mermaid flowcharts and sequence diagrams make these handoffs visible:

Who does what, in order — a flowchart shows the sequence and decision points.
Who talks to whom — a sequence diagram shows when teams or roles communicate.
What blocks progress — decision diamonds highlight approval gates and dependencies.
Where people get stuck — documenting the workflow reveals pain points.

An approval workflow example

Here's a typical feature request that moves through multiple teams:

flowchart TD
    A[Product writes\nrequirement] --> B[Design reviews\nfor feasibility]
    B -->|Feedback| A
    B -->|Approved| C[Engineering\nestimates effort]
    C -->|Too complex| D[Product scopes\ndown]
    D --> B
    C -->|Approved| E[QA writes\ntest plan]
    E --> F[Engineering\nstarts sprint]
    F --> G[Engineering\ndeploys to staging]
    G --> H[QA tests\nand approves]
    H -->|Blocked| I[Engineering\nfixes bugs]
    I --> G
    H -->|Approved| J[Release to\nproduction]

By reading this once, anyone new understands:

Design reviews before engineering estimates.
Rejection loops back to the previous stage, not the start.
QA has a gate before release.

This one diagram replaces a wiki page that gets out of date.

Swimlane workflows for cross-team handoffs

When work crosses multiple teams, use subgraphs to show which team owns each step:

flowchart TD
    subgraph Product["Product Team"]
        A[Customer request] --> B{High priority?}
        B -->|No| C[Backlog]
        B -->|Yes| D[Scope requirement]
    end
    subgraph Design["Design Team"]
        E[Review scope] --> F{Design needed?}
        F -->|No| G[Pass to eng]
        F -->|Yes| H[Design exploration]
        H --> G
    end
    subgraph Eng["Engineering Team"]
        I[Implement] --> J[Code review]
        J -->|Changes needed| I
        J -->|Approved| K[Deploy]
    end
    D --> E
    G --> I
    K --> L[Monitor & close]

Each subgraph represents a team or role. The arrows that cross subgraphs are handoff points — document those explicitly in your onboarding.

Decision gates and approval checks

Some decisions block work. Highlight them with diamond nodes:

flowchart TD
    A[PR submitted] --> B{Needs\nsecurity review?}
    B -->|Yes| C[Add to security\nqueue]
    C --> D{Security\napproved?}
    D -->|No| E[Update code]
    E --> A
    D -->|Yes| F{Passes CI?}
    B -->|No| F
    F -->|No| G[Debug and fix]
    G --> A
    F -->|Yes| H[Merge to main]

This workflow shows that some PRs skip the security queue (if they don't touch sensitive code), but all must pass CI.

Communication sequences: who talks to whom and when

For workflows that depend on back-and-forth communication, sequence diagrams outshine flowcharts. They show timing and message ordering:

sequenceDiagram
    participant Eng as Engineering Lead
    participant PM as Product Manager
    participant Des as Design Lead
    participant QA as QA Lead

    PM->>Eng: New request + deadline
    Eng->>Des: Can you design by Friday?
    Des-->>Eng: Yes, need 2 clarifications
    Des->>PM: Have questions about requirements
    PM->>Des: Clarifications (reply)
    Des-->>Eng: Design ready for review
    Eng->>Des: Looks good, 1 small change
    Des->>Eng: Update deployed
    Eng->>QA: Ready for test planning
    QA->>Eng: Test plan shared
    Eng->>Eng: Development starts

This shows:

Who initiated the request (PM to Eng).
Parallel work (Design and Eng asking questions).
When people become unblocked (after PM replies).
The final handoff to QA.

Document the same workflow as a flowchart and it's hard to see who's waiting for whom. A sequence diagram makes it obvious.

Incident response workflows

When production breaks, clarity saves time. A Mermaid flowchart cuts through panic:

flowchart TD
    A[Issue detected] --> B[Alert on-call]
    B --> C[On-call investigates]
    C --> D{Root cause\nidentified?}
    D -->|No| E[Escalate to\nspecialist team]
    E --> C
    D -->|Yes| F{Hotfix\nneeded?}
    F -->|Yes| G[Code fix &\nQuick QA]
    F -->|No| H[Schedule for\nnext release]
    G --> I[Deploy to prod]
    H --> J[Add to sprint]
    I --> K[Monitor metrics]
    K --> L{Issue\nresolved?}
    L -->|No| C
    L -->|Yes| M[Post-mortem\nscheduled]

Print this and tape it to the war room. When an incident starts, teams follow a known path instead of improvising under stress.

Onboarding checklists as workflows

Turn a static checklist into a flowchart that shows when each step happens:

flowchart TD
    A[New hire starts] --> B[IT provides\nlaptop & access]
    B --> C[Manager does\nday-1 intro]
    C --> D[Engineering\nonboards to tools]
    D --> E[New hire\nstarts small task]
    E --> F[Get code review\nfeedback]
    F --> G{Comfortable\nwith codebase?}
    G -->|No| H[Pair with senior\nengineer]
    H --> E
    G -->|Yes| I[Assign first\nreal feature]
    I --> J[Regular\n1-on-1 check-ins]
    J --> K{Ramped up?}
    K -->|No| J
    K -->|Yes| L[Welcome to team!]

This diagrams more information than a checklist: the decision point (is the hire ready?), the feedback loop (pair programming if stuck), and the success condition (ramped up).

Tips for team workflow diagrams

Write the diagram in the same PR as you write the process. Document the workflow and live it at the same time; catch gaps immediately.
Use consistent shapes. Rectangles for actions, diamonds for decisions, rounded boxes for start/end. This creates a visual language your team internalizes.
Keep it current. When a workflow changes (new approval, different team), update the diagram in the same commit. A stale diagram is worse than no diagram.
Test readability with newcomers. Ask someone who just joined to read the diagram and walk through it. If they get lost, simplify.
Link from the diagram to the details. A diagram shows the happy path; link to a wiki page or code for exception handling and edge cases.
Version control your workflows. Store diagrams in your repo (docs/workflows/) so the history is git-searchable.

FAQ

What if our workflow is too complicated to diagram? If it's too complicated to diagram, it's too complicated. That's a signal to simplify the workflow itself, not give up on documenting it.

Should we update the diagram every time we change the workflow? Yes. If the diagram and the actual workflow diverge, the diagram becomes a liability — new people follow it and step off a cliff. Treat it like code: update in the same change set.

Can we use Mermaid to document our RACI matrix? Not cleanly with flowcharts, but a flowchart can show decision points where RACI matters. For a pure responsibility matrix, a table in your wiki works better.

How detailed should our diagrams be? Detailed enough to unblock a new team member, not so detailed that it replaces the full runbook. If someone needs 50 decisions, split it into 2–3 focused workflows.

Use the visual editor to draft your team's workflow, review it in a meeting, iterate until everyone agrees, then commit it to your repo.

Mermaid