3 posts tagged with "state-diagram"

The sprint board on the wall shows 40 items in "In Progress" and the rulebook says "we limit WIP" and nobody agrees on what the limit is. The board is honest; the documentation is aspirational. A Kanban diagram in the wiki is the board as a spec — columns, limits, and the rework paths drawn so the workflow is a claim the team can argue with.

Quick answer: document the team's board in Confluence as a Mermaid kanban, rendered by Mermaid Plus for Confluence. Columns as headings, work items as indented cards; the workflow rules (who may move what, when, including rework) as a stateDiagram on the same page. This post gives you three copy-paste examples.

The issue workflow lives in a wiki page that says "the approval chain is: team lead, then manager, then finance". The config says otherwise, the Jira post-function disagrees, and the incident report asks "who actually approved this?" — with three different answers on screen. A prose paragraph cannot hold a workflow; a diagram can, if it is the workflow.

Quick answer: document state machines and approval chains in Confluence as Mermaid stateDiagram-v2, rendered by Mermaid Plus for Confluence. Every legal state, every transition, every human decision on a labeled arrow — in editable text that stays true. This post gives you three copy-paste examples: an issue lifecycle, a spending approval chain, and a retry loop with a timeout.

State diagrams (also called state machine diagrams) model how a system transitions between discrete states in response to events. They are essential for documenting order lifecycles, user authentication flows, CI/CD pipelines, IoT device behavior, and any system where the current state determines what happens next. If your team uses Confluence for technical documentation, embedding state diagrams directly on your pages keeps your design decisions alongside runbooks, architecture decision records, and sprint planning notes.

In this tutorial, you will learn how to create state diagrams in Confluence using the Mermaid stateDiagram-v2 syntax. Every example is copy-paste ready, so you can drop it straight into a Confluence page and see the rendered result immediately.