Skip to content
BENIBIX Learn

Diagramming Software

Level 4 · Boards and diagrams

Tools for neat charts of boxes and arrows. Apps where you drag shapes, like draw.io. And tools where you type the chart, like Mermaid.

Course contentsLesson 12 of 12

After this lesson you can

  • Pick drag-and-drop or text diagrams
  • Write a two-box Mermaid diagram
  • Keep a diagram next to the code

12 mincovers 6 glossary entries

Worth reading first: Online Whiteboards

Two ways to draw a diagram: drag it or write it

Diagramming software draws neat charts of boxes, lines and labels, such as flowcharts and maps of a system. There are two kinds. In one, you drag shapes onto a page and the lines stay stuck to them. In the other, you type a few lines of text and the tool draws the picture.

draw.io is a free drag tool for the web and the desktop. It has big libraries of shapes, and it saves the file wherever you choose. The file is plain text inside, so it can sit in the same folder as a project's code and be checked like code.

Lucidchart is a drag tool that runs in the browser. Several people can edit one diagram at once and leave comments. It can build a chart from a spreadsheet. Your diagrams are kept in its cloud, with a free plan that has limits.

Mermaid is the best known text tool. You type a line like A --> B, and it draws box A with an arrow to box B. GitHub, GitLab and many note apps draw Mermaid inside their pages. Change two words of text, and the picture redraws itself.

PlantUML is an older text tool. You write lines between @startuml and @enduml, and it draws the picture. It covers the common software diagrams, like the steps between a shop and a bank. Structurizr goes further. You write one model of a system, and it draws several diagrams from it. Rename a part once, and every diagram changes.

Text diagrams win when the diagram lives next to code. A change to the diagram shows up in a review like any other line, and nobody hunts for the newest picture. Drag tools win when the reader is not a coder, or the layout needs a careful hand.

The common mistake is a diagram nobody updates. A neat picture of last year's system is worse than none, because people trust it. Keep diagrams where the work happens, and change them in the same step as the thing they show.

The same two boxes, made three ways. Sketched by hand, dragged into place, or written as two lines of text.
mermaid
flowchart TB
  A[Shop] --> B[Pay]

Five diagram tools

ToolHow you make itWhere the file lives
draw.ioDrag shapesWherever you save it
LucidchartDrag shapesLucidchart's cloud
MermaidWrite textIn your notes or code
PlantUMLWrite textIn your notes or code
StructurizrWrite one model, get many viewsIn your code

Which kind to pick

  1. 1

    Drag shapes

    Pick one when the readers do not code, or each box needs a careful hand.

  2. 2

    Write text

    Pick one when the chart lives next to code and should be checked along with it.

  3. 3

    One model, many views

    Pick it when one big system needs a few charts that must always match.

Worked example

A login flow that redraws itself

Emma keeps a Mermaid chart of the 6 steps to log in to her app. It sits in the notes for her project on GitHub.

When a new step is added, she types one more line. The picture redraws, and her teammate sees the change in the same review as the code.

The words for this lesson6

Check yourself

When is a text tool like Mermaid the better choice?

Finished this lesson?

Marking it complete also marks its 6 glossary entries learned, which updates your roadmap and your saved page. 0 are already marked.