Diagram Types — When to Use Each

Structure & relationships

• Architecture — Shows the components of a system (services, databases, queues, external APIs) and the connections between them. Use it when someone needs to understand how the pieces of a system fit together at a glance — onboarding a new engineer, documenting a service before a migration, or explaining a design in a review. Skip it if you only have 2-3 boxes with one connection; that's a sentence, not a diagram.
• ER / data model — Entities (tables/objects) with their fields and the relationships (one-to-many, many-to-many) between them. Use it when designing or documenting a database schema, or when you need to reason about how data is normalized and connected before writing migrations. Most useful early in a project, before the schema calcifies.
• Layer stack — Abstraction layers drawn as horizontal bands, stacked so lower layers support higher ones (e.g. hardware → OS → runtime → application, or OSI network layers). Use it to explain dependency direction between layers of abstraction — what sits on top of what, and what breaks if a lower layer changes.
• Nested — Hierarchy expressed by literally drawing boxes inside boxes (an org inside a division inside a company, or a VPC inside a region inside a cloud account). Use it when containment itself is the point — when something is physically or logically inside something else, not just related to it.
• Venn — Two or more overlapping circles showing what's shared vs. unique between sets. Use it for comparing scope or membership — feature overlap between two products, skill overlap between two roles, shared vs. distinct requirements between teams. Gets unreadable past 3 circles; don't force a 4-way Venn.
• Dependency graph — Nodes and directed edges showing what depends on what, including fan-in (many things depending on one), fan-out (one thing many others depend on), and cycles. Use it to find risky central dependencies, plan safe refactor order, or explain why one library change broke six unrelated services.
• UML class — Classes with their attributes, methods, and typed relationships (inheritance, composition, association) between them. Use it for object-oriented design docs, before writing code for a non-trivial class hierarchy, or when reviewing someone else's OOP design and you need to see the shape of it.
• Database schema — Physical tables with actual column names, types, and foreign key lines between them — more concrete and implementation-level than an ER diagram. Use it once the schema is built or close to final, as reference documentation for whoever queries or migrates the database next.

Flow & process

• Flowchart — Decision logic expressed as boxes and diamonds, with branches for different outcomes. Use it for any process with conditional branches — an approval workflow, a troubleshooting procedure, business logic with multiple if/else paths. If there's no branching, it's just a list — use a numbered list instead.
• Sequence — Actors (services, users, systems) as vertical lifelines, with horizontal arrows showing messages passed between them over time, top to bottom. Use it for anything where order and timing between parties matters — an API request/response cycle, an OAuth token refresh flow, a distributed transaction across microservices.
• State machine — States as nodes, transitions as labeled edges between them, showing what triggers a move from one state to another. Use it for anything with a finite, well-defined lifecycle — an order's status (pending → paid → shipped → delivered), a connection's states, a UI component's modes. If a system can be in infinitely many configurations, this isn't the right tool.
• Swimlane — A flowchart split into horizontal or vertical lanes, one per team/role/system, showing who does what and where work crosses a boundary. Use it when a process spans multiple owners and the handoffs between them are the interesting part — e.g. an incident response process moving between on-call, engineering, and comms.
• Process — A multi-actor sequential workflow, similar to swimlane but framed around ordered steps rather than lane ownership. Use it for step-by-step operational workflows involving more than one participant, where you want the sequence to read left-to-right or top-to-bottom rather than lane-by-lane.
• Data flow — Pipeline steps scoped to specific roles or systems, showing how data moves and transforms from source to destination. Use it to document an ETL/ELT pipeline, a data ingestion path, or any process where the main story is data being transformed as it passes through stages.
• Sankey — Flow width is proportional to quantity, and flows can split and merge — the classic "where did the volume go" diagram. Use it when quantity itself carries meaning: budget allocation across categories, user funnel volume splitting into different paths, energy or material flow through a system. Wrong tool if the flows aren't quantitative.
• Fishbone — A central "spine" (the effect/problem) with angled "bones" grouping contributing causes into categories. Use it for root-cause analysis — postmortems, quality issues, "why did this fail" investigations where causes cluster into categories (people, process, tools, environment, etc.).
• Deployment — Physical or logical deployment topology: zones, hosts, and the artifacts running on each. Use it to document where things actually run — which services live in which network zone, on which hosts or clusters — useful for infra reviews, security audits, and incident diagnosis.

Hierarchy & ranking

• Tree — Parent-to-children branching, no cross-links. Use it for anything strictly hierarchical with a single path down from any node to the root — file system structure, a decision tree, a taxonomy, a component breakdown.
• Org chart — People or teams with reporting lines and, optionally, routing/ownership indicators. Use it for team structure, escalation paths, or "who owns what" documentation — anywhere the hierarchy is about people/teams rather than abstract concepts.
• Pyramid / funnel — A ranked hierarchy (base = most foundational/most volume) or a funnel narrowing toward a smaller output (e.g. conversion funnel). Use a pyramid for priority or maturity models (Maslow-style); use the funnel framing specifically when you're showing drop-off between stages, like a sales or signup funnel.
• Story map — A horizontal "backbone" of user activities, with vertical slices showing what's included in each release. Use it for product/agile planning — mapping a user journey against release scope, so everyone can see what's in v1 vs. later.
• Kanban — Columns representing workflow states (to do / in progress / done, or more granular), with cards moving across them. Use it to show current work-in-progress distribution across a pipeline, or as a snapshot of a team's board at a point in time for a status update.

Comparison & positioning

• Quadrant — Two axes crossing to form four quadrants, items placed by where they score on each axis. Use it for prioritization (impact vs. effort), positioning (build vs. buy, cost vs. value), or any comparison that reduces cleanly to two independent dimensions.
• Radar / spider — Multiple axes radiating from a center, one shape per item being compared, showing relative strength across many dimensions at once. Use it when you're comparing 2-4 options across 4+ criteria simultaneously — vendor comparisons, skill assessments, product feature comparisons. Gets messy with more than a few overlapping shapes.
• Wardley map — Value chain position (how visible/close to the user) on one axis, evolution stage (genesis → custom-built → product → commodity) on the other. Use it for strategic technology or business planning — deciding what to build vs. buy vs. outsource based on how commoditized a capability is. Niche but powerful in strategy contexts; don't reach for it outside that use case.
• Polar chart — Similar to radar but encodes a cyclic magnitude with a linear radius — think of periodic/cyclical data (time of day, seasonal patterns) mapped around a circle. Use it specifically for cyclical quantitative data where the "wraparound" nature of the axis matters, unlike a radar chart's fixed set of categorical axes.

Time-based

• Timeline — Discrete events plotted along a single time axis. Use it for historical narratives, project milestones, or any story that's fundamentally "this happened, then this happened."
• Gantt — Tasks and phases as horizontal bars along a timeline, showing duration and overlap. Use it for project planning and scheduling — when you need to show not just that things happened in sequence but how long each took and where they overlapped.
• User journey — Stages of an experience, the user's actions at each stage, and their sentiment (frustration, delight) plotted alongside. Use it for UX research and product design — surfacing where in a flow users struggle, to prioritize what to fix.
• Loop / flywheel — A circular flow representing a reinforcing cycle, often with a shared hub in the middle that all the loop's stages feed back into. Use it for business models or systems that compound over time — growth loops, feedback loops, virtuous cycles — where the point is that the cycle strengthens itself with each pass.

Charts (quantitative)

• Bar chart — Categorical comparison, bar length/height proportional to value. Use it for comparing discrete categories against each other — sales by region, votes by candidate. The default choice for "compare these numbers."
• Line chart — Trend over a continuous axis, usually time. Use it whenever the trajectory matters more than any single value — revenue over quarters, a metric drifting up or down.
• Scatter plot — Individual data points plotted on two numeric axes, revealing distribution and correlation. Use it when you have many data points and want to see whether/how two variables relate, or to spot outliers and clusters.
• Treemap — Rectangles sized by value, nested to show part-of-whole relationships (e.g. storage used by folder, revenue by product line). Use it for hierarchical proportions where area itself needs to communicate scale — this only works if the area-to-value mapping is accurate, so it's less forgiving than a bar chart of small errors.

Data-platform specific

• Medallion — Multi-tier data storage architecture, typically bronze (raw) → silver (cleaned) → gold (aggregated/business-ready). Use it specifically when documenting a data lakehouse or similar layered data architecture — this is a domain-specific variant of the layer stack, tailored to data engineering vocabulary.
• DP integration — Sources feeding into a core platform, which feeds out to consumers. Use it to document a data platform's ingestion and distribution boundaries — what comes in, what the platform does, who/what consumes the output.
• DP security matrix — A grid of roles against resources/permissions, showing who can access what. Use it for access-control documentation and audits — a compliance or security review needs exactly this shape: role rows, resource columns, permission cells.

When not to diagram at all

• Quick throwaway visuals for a chat message or terminal output — plain text is faster and just as clear.
• A list of anything — a table or bullet list beats a diagram every time.
• Before/after comparisons — a table communicates this more precisely than boxes and arrows.
• A single labeled box — if there's only one shape, you don't have a diagram, you have a sentence. Write the sentence.

The underlying test: would a reader learn more from this than from a well-written paragraph? If not, don't draw it.