Charts and graphs

Charts in Confluence usually arrive as screenshots of a spreadsheet, which means nobody can check the numbers or change the axis. A chart rendered from a text spec keeps the data visible and editable.

Vega-Lite covers most needs in a few lines; Mermaid handles the simple cases with even less.

#When to reach for one

• Reports where the numbers should be reviewable, not just viewable.

• Small datasets that live in the document rather than a warehouse.

• Anywhere a screenshot of a chart is currently being pasted.

#How to draw it in Capable

#A worked example

A bar chart, data and all, in one spec:

The source, which you can paste into a new diagram and edit:

{
  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
  "description": "Support tickets by category",
  "data": {
    "values": [
      {"category": "Billing", "tickets": 42},
      {"category": "Access", "tickets": 31},
      {"category": "Performance", "tickets": 27},
      {"category": "Data", "tickets": 18},
      {"category": "Other", "tickets": 9}
    ]
  },
  "mark": "bar",
  "encoding": {
    "y": {"field": "category", "type": "nominal", "sort": "-x"},
    "x": {"field": "tickets", "type": "quantitative", "title": "Tickets"}
  }
}

#Which chart for which question

#A few things that catch people out

• The data lives in the spec, so it is a snapshot. Say when it was taken.

• Sort categorical bars by value unless the order means something.

• Pie charts are hard to read above about five slices. A sorted bar chart is almost always better.

#Related

Keep the numbers where people can check them.