Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Drawing principles

drumlin aims to draw like a careful draftsman: someone who knows the notation, works on squared paper with one pen, and redraws a line rather than leave it crooked. The drawing should look deliberate. Every line is straight unless it has a reason to turn, every label sits where it can belong to only one thing, and the space between shapes is even.

This part of the book states that aesthetic as explicit rules. Each rule says what drumlin does now or what it should do, so that a change to the layout can be judged against it.

A careful drawing Idle Paused Running start pause resume stop

The state diagram above follows the rules. It flows one way, from top to bottom. The lines are orthogonal, and none of them crosses another. Each label sits beside its own line. The reverse pair between Running and Paused runs as two parallel lines, with their labels on the outside. The one line that turns, stop, turns because three lines share the bottom of Running.

How rules are written

Each principle has:

  • a name, in the imperative, such as Avoid crossings;
  • the rule itself;
  • why it matters;
  • a source: the aesthetics research report in the repository (docs/research/diagram-aesthetics.md), the studies it cites (Purchase 1997 and 2002, Ware et al. 2002, Gansner et al. 1993, Wybrow et al. 2009), the UML 2.5.1 specification, or drafting practice;
  • its status in drumlin:
    • enforced: drumlin does this in every diagram it lays out, and the named stage of How layout works is where;
    • partial: drumlin does this in some diagram kinds or cases, or tries but does not guarantee it;
    • planned: drumlin does not do this yet. The Layout levers study measures what it would gain, where that was measured.

Where it helps, a rule shows a good drawing, rendered by drumlin, and describes or sketches the bad one.

When rules conflict

Rules conflict all the time. A label wants the straight line’s gap, which another line wants too. Growing a box straightens a connector but makes a row uneven. drumlin settles each conflict in this order, highest first:

  1. Correct notation. The UML 2.5.1 notation is never traded for looks. A package with contents keeps its name in the tab, even where a line would run straighter without the tab.
  2. Unambiguous reading. Every line, label and name must belong visibly to one thing. A label floating between two lines, an arrowhead on a corner, or two connectors leaving one point together are worse than any jog.
  3. No overlaps. No shape on a shape, no line on a line, and no line through a shape or a name. Two lines on one lane cannot be told apart, so this ranks above crossings, as the nudging stage ranks it.
  4. No crossings. Crossings matter most in every human-factors study of graph drawing (Purchase 1997; 93% preference in Purchase et al. 2002).
  5. Few bends. Bends come next in the preference data (91%), and continuity of a path helps it be traced (Ware et al. 2002).
  6. Flow and alignment. A single direction, ranks, centred and symmetric placement.
  7. Compactness. Small area and short lines, but never at the cost of the rules above.
  8. Uniformity. Even box sizes and even spacing. This is the first rule to give way: a box may grow to straighten a line.

The order follows the research summary: crossings first, then bends, with orthogonality held throughout by construction. Readability and notation sit above everything, because a drawing that reads wrongly is worse than one that reads slowly.

The pages