Diagrams

When you’ve to create diagrams, try to avoid native tools, and use open-source web-based solutions.

Mermaid

We’re using Mermaid for our diagrams as code. Mermaid diagrams are written in a simple, Markdown-inspired text syntax, which makes them easy to read, review & version in Git.

Hint

AI assistants (e.g. Claude) are great at writing Mermaid diagrams, and can render them right away.

Mermaid documentation

The official documentation for Mermaid can be found here:

• Intro (good for starting)

• Syntax reference

• Flowcharts

• Sequence diagrams

Mermaid in GitLab & Sphinx

GitLab supports inline Mermaid diagrams in GitLab Flavored Markdown out of the box, so you can use them in all of your *.md files and work items.

You can also build Mermaid diagrams in your docs. Just have a look at the Documentation chapter.

PlantUML

We’re running our own PlantUML Server to create our own PlantUML diagrams.

PlantUML documentation

Since the official docs are quite “adventurous” to understand, you might want to have a look at Ashley’s PlantUML Documentation. Some interesting chapters are:

• All Diagrams

• Formatting Diagrams with Skinparams, HTML, and Creole

• Color Names and Samples

• Creole Markup

• All Skin Parameters

The official documentation for PlantUML can be found here:

• PDF Guide (good for starting)

• PlantUML website

• Standard Library

• Language specification

• The Hitchhiker’s Guide to PlantUML

PlantUML in GitLab & Sphinx

GitLab supports inline PlantUML diagrams in GitLab Flavored Markdown out of the box, so you can use them in all of your *.md files and work items.

You can also build PlantUML diagrams in your docs. Just have a look at the Documentation chapter.

draw.io

We’re running our own draw.io server to create our own draw.io diagrams.