Category: Documentation

State diagrams answer a different question than flowcharts and sequence diagrams. Flowcharts: What steps happen? Sequence diagrams: What calls happened in what order? State diagrams: What states can this thing be in, and what events move it between states? If you’ve ever tried to explain “healthy → draining → terminated” (or “closed → open → half-open”), a state diagram is usually the cleanest way to do it. This post focuses on Mermaid state diagrams for modeling lifecycles you’ll actually run into in ops and engineering: deploys, load balancers, workers, and circuit breakers. A quick refresher: the minimum you need Mermaid’s modern syntax is stateDiagram-v2. Source

Rendered Conventions worth adopting Use nouns for states: Healthy, Draining, Degraded Use verbs/events on arrows: timeout, deploy, deregister, success Keep labels short; if you need paragraphs, add a note or link to a runbook 1) Model “system lifecycle” states (a great first use) Many