Use Mermaid for flows that should remain searchable, editable, and easy to maintain in notes. Use Excalidraw when spatial exploration matters more than structure.

Flowchart Template

Define nodes first, then their relationships:

flowchart TD
    receive_request[Receive feature request]
    check_clarity{Is the request clear?}
    clarify_request[Clarify requirements]
    estimate_effort[Estimate effort]
    ready_backlog[Add to backlog]

    receive_request --> check_clarity
    check_clarity -- No --> clarify_request
    clarify_request --> check_clarity
    check_clarity -- Yes --> estimate_effort
    estimate_effort --> ready_backlog

Naming

  • Use descriptive snake_case IDs: estimate_effort, not A or step1.
  • Start process IDs with a verb: send_invoice.
  • Name decisions as checks: is_valid, has_approval.
  • Keep IDs unique and separate from their displayed labels.
  • Prefer letters, numbers, and underscores; avoid lowercase end, which can break parsing.

Common Syntax

SyntaxMeaning
flowchart TDTop to bottom
flowchart LRLeft to right
id[Label]Process
id{Question?}Decision
id([Label])Start or end
a --> bRelationship
a -- Yes --> bLabelled relationship

Guidelines

  • Keep one diagram focused on one flow.
  • Write short labels; put explanations below the diagram.
  • Label decision branches consistently, such as Yes / No.
  • Use descriptive IDs for maintained notes; A, B, and C are fine for disposable diagrams.
  • Add styling only when it communicates meaning.