Ishikawa diagrams in Confluence

An Ishikawa diagram, also called a fishbone diagram, sorts the possible causes of a problem into categories.

Last updated

When to use it

Use an Ishikawa diagram in a post-mortem or a quality review. The problem is the head of the fish; each bone is a category, such as people, process or tooling, with its causes. It pushes the team to look at every category before choosing one cause.

Example

This is the code of the Outage root causes template: a fishbone post-mortem of an outage, causes grouped in six categories.

ishikawa-beta
  Checkout down for 18 minutes
  Code
    Null pointer in cart total
    Retry loop without backoff
  Database
    Connection pool exhausted
    Missing index on orders table
  Configuration
    Wrong timeout in production
    Feature flag left enabled
  Monitoring
    No alert on error rate
    Dashboard showed stale data
  External dependencies
    Payment gateway slow
    DNS resolver timeouts
  Release process
    Deployed on Friday evening
    Canary stage skipped

Vellnar Diagrams draws it like this:

Change a line and the diagram changes with it. Nobody needs the original drawing file, because there is none: the code is the diagram.

Add it to a Confluence page

  1. Edit a Confluence page and type /mermaid where the diagram should go.
  2. Select Mermaid diagram. The editor opens with the template list.
  3. Pick a template, or choose Start blank and paste the code above. The preview follows every keystroke.
  4. Choose Save. The diagram appears on the page.

The documentation covers the editor, the settings and the exports.

Templates

The Templates button in the editor has one Ishikawa diagram ready to use:

  • Outage root causes: A fishbone post-mortem of an outage, causes grouped in six categories.

Syntax

The code of a Ishikawa diagram starts with ishikawa-beta. The Mermaid documentation describes every element of the syntax. Vellnar Diagrams draws it with Mermaid 12.3; if a line has an error, the editor marks the line and keeps the last valid diagram on screen.

More

  • Mermaid in Confluence: how diagrams as code work in a page, and every diagram type.
  • Security: the app asks for no permissions and sends nothing outside Atlassian.