Flowchart

1. Pick the diagram

You are showing	Use
Steps and decisions	flowchart TD (or LR for wide, shallow flows)
Messages between actors over time	sequenceDiagram
An object's lifecycle	stateDiagram-v2
Data model	erDiagram
Timeline / plan	gantt or timeline

2. Gather the flow

List: start, end(s), each step (verb + object), each decision (a yes/no or short-answer question), loops and failure paths. Read the code if it is a code flow; don't diagram what you assume.

3. Conventions

• Rounded (…) start/end, rectangles […] steps, diamonds {…} decisions.
• Quote labels: A["Validate input"]. Avoid raw (), ;, # in labels.
• Decisions are questions; edges are answers: -- "Yes" -->.
• 5–15 nodes. More? Split into subgraphs or a second diagram.
• One direction. Happy path straight down; errors branch to the side.
• IDs are short (A, B, V1); text goes in labels.
• Dotted -.-> for optional/async; thick ==> for the main path if needed.

4. Example

flowchart TD
  S(["Request"]) --> A["Validate input"]
  A --> B{"Valid?"}
  B -- "No" --> E["Return ERR_VALIDATION"]
  B -- "Yes" --> C["Save"]
  C --> D(["201 Created"])

5. Check

• Every decision has all its exits labelled.
• No dead ends except real end states.
• It renders (paste into a Mermaid live editor or your docs preview).
• Someone new can follow it without the prose.

Customize for your project

Where diagrams live ({{DOCS_DIR}}/diagrams) and your theme (%%{init: {...}}%%).