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_caseIDs:estimate_effort, notAorstep1. - 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
| Syntax | Meaning |
|---|---|
flowchart TD | Top to bottom |
flowchart LR | Left to right |
id[Label] | Process |
id{Question?} | Decision |
id([Label]) | Start or end |
a --> b | Relationship |
a -- Yes --> b | Labelled 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, andCare fine for disposable diagrams. - Add styling only when it communicates meaning.