Venn diagrams

TL;DR

Ask your agent

Use Plotwork to draw a Venn diagram of who owns what between the Frontend, Backend and Platform teams. Name the overlap of Frontend and Backend "API contracts" and the overlap of all three "On-call", and put each piece of work in the region of the teams that share it.

Use Plotwork to draw a Venn diagram, to scale, of the users of our web app and our mobile app: 900 on the web, 500 on mobile, and 200 who use both.

Example

Three teams, the work each owns alone, the two overlaps that have a name, and the work they share. Each set has a tone and an icon; without them the sets take blue, violet, aqua and orange in turn.

PictureSourceOutline

Two sets to scale

With sizes=on, two sets are drawn to scale: each circle's area is its set's size=, and the overlap's area is the overlap's size=. The numbers are written in the tabs and the overlap.

PictureSourceOutline

Four sets

Four sets are drawn as four tilted ellipses, so every combination has a region. The smallest regions are small, so name only the overlaps that matter; a region that cannot hold its text shows a number, and the key beside the shapes lists it.

PictureSourceOutline

The language

One statement to a line. Text is always in double quotes, options are key=value, and # starts a comment.

The header

venn "Title" sizes=off desc="<text>". The title, sizes= and desc= are optional. sizes=on draws two sets to scale; with sizes=off, the default, the shapes are equal and any sizes are written as numbers.

Statements

Sets

A set has an id, which overlaps and items name, and a label, which is drawn in a tab outside its shape. Give it a tone= for what it means and an icon= when a glyph helps; the tab shows the icon, the label and the size. One set is a circle, two are side by side, three sit on a triangle, and four are tilted ellipses. A fifth set is refused, because five shapes cannot show every overlap in a way a reader can follow: use a matrix instead.

Overlaps and items

An overlap names a region of two or more sets, and its name is drawn in that region. The order of the ids does not matter, and each region is named once. An item lives in the region of exactly the sets it names: item fe "Design system" is in Frontend and no other set, and item fe be ops "Incident drills" is in all three. An overlap or item may name a set declared further down.

Each region's text is centred in it and kept 8px from every outline. When a region cannot hold its items, its name stays if it fits, a numbered badge marks the region, and the items are listed in a key beside the shapes under that number. The key keeps the full text.

Sizes

size= on a set or an overlap is a plain number, such as 30 or 2.5. With sizes=off the number is written in the set's tab and under the overlap's name. With sizes=on and two sets that both have a size, the circles are drawn to scale; an overlap of size=0 parts them, and its items go to the key. Three or four sets cannot be drawn to scale with circles, so they stay equal and lint says so. A set far smaller than the other is drawn at a third of the larger radius so its text has room, and lint says that too.

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's Venn diagram (venn-beta, and venn) converts to a Venn diagram. Ask your agent to convert it, or use the convert_mermaid tool. The migration guide covers the converter in full.

1venn-beta2  title Team overlap3  set A["Frontend"]4    text A1["React"]5    text A2["Design Systems"]6  set B["Backend"]7    text B1["API"]8  union A,B["Shared"]9    text AB1["OpenAPI"]

It becomes:

1venn "Team overlap"2
3set A "Frontend"4set B "Backend"5
6overlap A B "Shared"7
8item A "React"9item A "Design Systems"10item B "API"11item A B "OpenAPI"

A text line belongs to the latest set or union above it. Then give each set a tone and an icon, and name the overlaps that mean something.

See also