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
Level 1 · Picking a design app
Level 2 · Designing screens
Level 3 · Drawing and editing
Level 4 · Boards and diagrams
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.
flowchart TB
A[Shop] --> B[Pay]Five diagram tools
| Tool | How you make it | Where the file lives |
|---|---|---|
| draw.io | Drag shapes | Wherever you save it |
| Lucidchart | Drag shapes | Lucidchart's cloud |
| Mermaid | Write text | In your notes or code |
| PlantUML | Write text | In your notes or code |
| Structurizr | Write one model, get many views | In your code |
Which kind to pick
- 1
Drag shapes
Pick one when the readers do not code, or each box needs a careful hand.
- 2
Write text
Pick one when the chart lives next to code and should be checked along with it.
- 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.