Miscs

• Diagram Types — When to Use Each
• Decision-Making & Thinking Methods — When to Use Each

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.

Decision-Making & Thinking Methods — When to Use Each

Elimination-based methods

• Process of elimination — Systematically ruling out options that fail a hard requirement until only viable ones remain. Use it when you have many options and at least one clear disqualifying criterion (budget cap, hard deadline, legal requirement) — it's fast because you never have to score the options you kill off. Bad fit when no option can be truly disqualified and everything is a matter of degree; then you need scoring, not elimination.
• MECE exclusion (Mutually Exclusive, Collectively Exhaustive) — Breaking a decision space into buckets that don't overlap and don't leave gaps, then eliminating whole buckets at once instead of individual items. Use it when the option space is large and unstructured (e.g. "how do we reduce costs") — forcing MECE buckets first prevents you from redundantly comparing options that are really the same idea in different words.
• Veto voting — Each participant can strike out options they find unacceptable, and whatever survives every veto wins. Use it in group decisions where avoiding a bad outcome matters more than optimizing for a great one — picking a restaurant for a group with dietary restrictions, or approving a shortlist where any single stakeholder can kill a candidate.

Branching / tree-based methods

• Decision trees — Mapping out sequential decision points as branches, with the outcomes and probabilities at each leaf. Use it when a decision unfolds in stages and later choices depend on earlier ones — should we invest now or wait for more data, given different ways the market could move. Overkill for one-shot decisions with no sequential dependency.
• Backward induction — Starting from the desired end state or last decision point and reasoning backward to figure out what has to be true at each earlier stage. Use it for planning problems with a known target and multiple paths to it — game theory, negotiation prep, or working out the last responsible moment to make a call. Only works cleanly when the end state is well-defined; useless for open-ended exploration.
• Minimax / worst-case branching — At each decision branch, assume the opponent or environment will pick the outcome worst for you, and choose the branch that minimizes that worst case. Use it in adversarial or highly uncertain situations where you can't assign real probabilities — competitive strategy, security threat modeling, negotiating with an unpredictable counterparty. Too conservative for situations where you actually have decent probability estimates; expected-value methods do better there.

Comparative / scoring methods

• Weighted decision matrix — List options as rows, criteria as columns, assign a weight to each criterion, score each option per criterion, and sum. Use it when you have 3+ options, multiple criteria that matter to different degrees, and you want a defensible, auditable comparison — vendor selection, hiring between finalists, picking between architecture options. Don't bother for a 2-option call with one dominant criterion; that's just a comparison sentence.
• Pairwise comparison — Comparing every option against every other option one-on-one, then tallying wins, instead of scoring all of them on an abstract scale at once. Use it when abstract scoring feels arbitrary or when direct comparison is easier for people than absolute rating — ranking a shortlist of candidates, or prioritizing a backlog where "how much better is A than B" is easier to answer than "rate A from 1-10."
• Pros/cons list — The simplest form: two columns, upsides and downsides, no weighting. Use it for quick, low-stakes personal decisions where you mainly need to externalize your thinking, not calculate an optimum. Weak for anything with more than a couple of criteria of very different importance — a long pros list can outweigh one severe con it shouldn't.
• Cost-benefit analysis — Converting the expected costs and benefits of each option into comparable units (usually money or time) and comparing net values. Use it for decisions with quantifiable costs and benefits — capital investment, whether to build vs. buy, whether a project is worth the resourcing. Breaks down when the biggest factors are genuinely unquantifiable (reputation, morale); forcing a number onto those can mislead more than it helps.

Root-cause & diagnostic methods

• Five Whys — Asking "why" repeatedly (usually 5 times) on an observed problem until you reach the root cause rather than a symptom. Use it right after an incident or failure, when the visible problem is probably a downstream effect of something deeper — a production outage, a recurring team conflict, a process that keeps breaking. Weak when a single problem has multiple independent root causes; the format's single-chain structure will make you stop at the first plausible-sounding answer instead of finding all of them.
• Fishbone / Ishikawa diagram — Mapping many possible contributing causes, grouped into categories (people, process, tools, environment), converging on one effect. Use it when a problem plausibly has several independent contributing factors and you want to explore breadth before committing to one root cause — quality defects, complex incident postmortems. More effort than Five Whys, but better suited to multi-causal problems.
• First principles thinking — Stripping a problem down to its fundamental truths and reasoning up from there, instead of reasoning by analogy to how it's normally done. Use it when the standard approach to a problem is expensive, slow, or just assumed rather than justified — redesigning a process everyone "always" does a certain way, or challenging an industry convention. Costly to do for routine decisions; reserve it for decisions where the payoff of a genuinely novel answer is high.

Framing & structuring methods

• SWOT analysis (Strengths, Weaknesses, Opportunities, Threats) — A four-quadrant framing that separates internal factors (strengths/weaknesses) from external ones (opportunities/threats). Use it early in strategic planning, when you need a shared, structured starting point for a discussion rather than an actual decision — it's a framing tool, not a decision procedure, so don't expect it to output an answer by itself.
• Six Thinking Hats — Deliberately switching between six modes of thinking (facts, feelings, caution, optimism, creativity, process) in turn, usually in a group. Use it when a group discussion keeps getting stuck because people default to one mode (usually caution or optimism) and talk past each other — it forces everyone to visit the same mode together instead of arguing across modes.
• Cynefin framework — Classifying a situation as simple, complicated, complex, or chaotic, and matching your decision approach to that classification (best practice, good practice, emergent practice, or rapid stabilizing action respectively). Use it as a first step before choosing any other method on this list — it tells you whether a decision even has a knowable right answer (simple/complicated) or whether you should be probing and adapting instead (complex/chaotic).

Iterative / adaptive methods

• OODA loop (Observe, Orient, Decide, Act) — A fast repeating cycle for decisions under time pressure and incomplete information, where you act, then immediately re-observe and adjust. Use it in fast-moving, high-uncertainty situations where waiting for full information means missing the window to act — incident response, competitive/adversarial situations, live operational decisions. Wrong tool for decisions where you have time to gather full information up front; the speed advantage isn't worth the lost rigor.
• PDCA / iterative improvement (Plan, Do, Check, Act) — Running small experiments in a loop, checking results, and adjusting before scaling up. Use it for process improvement where you can test cheaply before committing — a new workflow, a process change, an experimental feature. Not suited to one-shot, high-stakes, irreversible decisions where you don't get a second iteration.
• Satisficing — Choosing the first option that meets a "good enough" threshold, rather than searching for the optimum. Use it when the cost of continued search or analysis exceeds the expected gain from finding a marginally better option — routine purchasing decisions, hiring under time pressure, anything where "good enough, now" beats "perfect, eventually."

Group / consensus methods

• Delphi method — Anonymously collecting expert opinions in rounds, sharing an aggregated summary between rounds, and repeating until opinions converge. Use it for forecasting or expert judgment on questions with no hard data, where you want to avoid groupthink and status-driven bias — long-range technology forecasts, expert risk assessments. Slow; not for time-pressured decisions.
• RAPID / RACI — Frameworks that assign explicit decision roles (who Recommends, who Agrees, who Performs, who has Input, who Decides / who's Responsible, Accountable, Consulted, Informed). Use it when a decision keeps stalling because it's unclear who actually has the authority to decide, not because the content itself is unclear — organizational decisions with many stakeholders. Doesn't help at all with the substance of the decision, only the process of making it.
• Dot voting / brainstorming convergence — After open brainstorming generates many options, each participant places a limited number of votes (dots) on their preferred ones, and the highest-vote options move forward. Use it to converge a large, unstructured set of ideas from a group down to a shortlist quickly, without a full scoring exercise — workshop facilitation, feature prioritization sessions.

Heuristics / shortcuts

• Pareto principle (80/20) — Recognizing that a small fraction of causes/inputs typically drives most of the effect/output, and focusing effort there instead of treating all factors equally. Use it for prioritization when you have many candidate causes or actions and limited time — which bugs to fix first, which customers to focus retention efforts on.
• Occam's razor — Among competing explanations that fit the evidence equally well, preferring the simplest one. Use it during diagnosis or root-cause analysis when multiple explanations are consistent with what you've observed — don't reach for an exotic explanation when a mundane one accounts for the same facts.
• Premortem — Before committing to a plan, imagining it has already failed and working backward to figure out why. Use it right before locking in a significant decision, as a check against overconfidence and groupthink — it surfaces risks that "will this work" framing tends to suppress because everyone's already invested in saying yes.
• Regret minimization — Choosing the option that minimizes your future regret if it turns out badly, rather than the option with the best expected value. Use it for personal, high-stakes, largely irreversible decisions where the emotional cost of "what if" outweighs a purely numerical optimum — career changes, major life decisions.