Matrices

TL;DR

Ask your agent

Use Plotwork to draw a matrix comparing Kafka, RabbitMQ, Amazon SQS and NATS as message brokers. Use throughput and ease of ops as scores, ordering and a managed offer as yes, no or partial, and the typical cost as text. Recommend Kafka.

Use Plotwork to draw a decision matrix for choosing a database. Score PostgreSQL, MySQL, MongoDB, DynamoDB and SQLite from 0 to 5 on query power, scale, ops effort and ecosystem, weight query power three times and scale and ops effort twice, and recommend the highest total.

Use Plotwork to draw a permission matrix for the Orders API. The columns are the roles guest, customer, support, finance and admin, each with an icon. The rows are the endpoints, such as GET /orders/:id, with what each does under it. Mark each cell allowed, denied, or partial, and add a legend that says partial means own records only.

Use Plotwork to draw a RACI chart for shipping release 2.4. The roles are engineering lead, QA, product, support and ops, and the tasks are freezing the scope, cutting the branch, running the regression tests, writing the release notes, deploying and telling customers. Give every task one Accountable role.

Use Plotwork to draw a risk heat map for the launch. Place eight risks by likelihood and impact, with an icon on the ones that need a name to stand out.

Example

Four message brokers compared on five criteria. Throughput and ease of ops are scores, ordering and the managed offer are answers, and the cost is text. The recommended row has a tone wash, a stronger outline, and a tab that says so.

PictureSourceOutline

The language

One statement to a line. Text is always in double quotes, options are key=value, and # starts a comment. A cell is not an option, so the cells of a row follow a colon and are separated by commas.

The four styles decide which statements and which cells are valid. A statement that belongs to another style is refused with a hint that says where it goes.

Cells

Each kind of cell has its own mark, so the table reads at a glance and still makes sense in grayscale.

A score above 5 is refused, and for a score out of 10 the hint says what to write. A number that is not whole is refused too, so a dot is never half drawn.

A half disc means something different in every table, so say what it means with a legend line: legend partial="Own records only". The legend draws the same discs under the table with their words, and the text description reads each named mark as its words. When a cell is partial and no legend names it, lint warns.

A permission matrix

Roles are the columns and endpoints are the rows, so a reader finds who may call what at a glance. Give each role an icon, put what the endpoint does in sub=, and name the marks in a legend. Quote a route such as "GET /orders/:id": a slash is only allowed inside quotes.

PictureSourceOutline

Weights and totals

Write weight=3 on a column to make it count three times as much in the total, and total=on on the header, or style=score, to add the column. The total of a row is the sum of each score times the weight of its column, drawn as a number with a bar for its share of the most it could be. Only scores add up: a column of yes and no answers or text leaves the total alone, and a cell that is not a score in a column of scores adds nothing, so lint says so.

Each weight is a small pill under its title, so a reader sees why a column counts for more. The total is also in the text description, so an agent can check the sum.

PictureSourceOutline

Recommending a row

recommend "Kafka" names one row, and a matrix recommends one row. The row is lifted into a card with a wash of its tone (green when the row has no tone=), a stronger outline, and a Recommended tab in its corner, drawn the way a group's name is in a flow diagram. The matrix never picks the winner for you: when the recommended row has a lower total than another, lint warns and suggests saying why in desc=.

A RACI chart

With style=raci the columns are roles and the rows are tasks. Each letter is a disc, and the stronger the role the more solid the disc: Accountable is filled, Responsible is a wash with a border, Consulted is a plain ring, and Informed is a dashed ring. A legend of the four letters sits under the table. A cell may name several roles, written as "A R", and they draw side by side with the strongest first.

PictureSourceOutline

A risk heat map

With style=risk there are no rows or columns. Each item is placed by its likelihood and impact, both from 1 to 5, in a grid of 25 cells. A cell takes a band from likelihood times impact: low for 1 to 4, moderate for 5 to 9, high for 10 to 16, and critical for 17 to 25, shaded from green through amber and orange to red, with the bands named in a legend. The first row is the highest impact and the first column the lowest likelihood, so the worst risks are at the top right. Several items in one cell stack as chips, and the row grows to hold them. Name the levels with levels when the defaults do not fit: they run from Rare to Almost certain and from Negligible to Severe.

PictureSourceOutline

Options and colour

The theme owns every color. A tone sets the dots, the bar, the icon chip, and the recommended card of a row, and a RACI chart draws every role in the tone of its row, so a tone= on a row marks something else, such as which team owns the task. Nobody writes a color value, so a matrix has real contrast in light and in dark.

Limits and warnings

Every mistake comes back as a result with a code, a line, a column, and a hint. Warnings never stop the drawing.

From Mermaid

Mermaid has no matrix type, so there is nothing for convert_mermaid to convert, and a Mermaid diagram that tries to be a table is better redrawn. A Markdown table is the usual source, and an agent can turn it into a matrix in one step: the header row becomes the columns line, each following row becomes a row line, and the cells become values.

Use Plotwork to turn this Markdown table into a matrix: write the header cells as columns, write each row as a row, turn a tick or the word yes into yes, a cross or no into no, and anything in between into partial, keep a number as a score from 0 to 5, and keep any other cell as quoted text.

If the table is a priority list with two scales, such as effort against impact, the quadrant chart places each item on both and reads the zone it falls in.

See also