Mermaid diagramming

Humans are visual thinkers. The first language invented by humans is not C or C++, nor it was
English. It was diagrams. Crude hand prints and stick figures on the walls of caves. We evolved so much
now that we have plenty of spoken languages to communicate with each other and plenty more to
communicate with machines. Yet our thinking starts with images inside our heads.
Developers are humans. Factoring in the formal education developers undergo. The bend of mind they
mould themselves into allows complex concepts visualised in the head. They do not draw everything. Often
experienced developers sparsely draw; that we assure is a completely wrong impression. Experienced
developers draw but they run a mile in their heads before drawing something on a sheet of paper. Only
because they could.
Combining the starting statements from the two paragraphs we can infer Humans are visual thinkers,
Developers are humans; thereby Developers are visual thinkers. It is very true. Developers do not write
code upfront. No matter how much any individual’s experience. If you had a personal goal of accomplishing
something like that where you could imagine the code in your mind before you press the first key in the
keyboard; we suggest you reconsider it. Always start with what is a low threshold activity to your brain.
Something, that does not require you to remember much of the rules. Something that helps you focus on
the core of the problem.
There were many solutions over time. This is not a novel problem. In the decades past developers had two
different applications one for writing code to instruct computers. Another is to communicate with other
humans; called teams and stakeholders. These two tools seldom interoperate with each other. That led to
tons of hours poured in doing things repeatedly without much business value.
Tools like Visio, and draw.io in recent times are a few we are sure you would have seen someone using
them. They were marred by the challenges mentioned earlier. Being separate from actual code. If you are
familiar with commotions that arise from such tools you might prompt to us PlantUML. Don’t worry if you did
not come across PlantUML. But the idea being simple text written in an intuitive manner helps produce a

diagram. The intuitive manner required one to write text in a manner which was compliant at least loosely
with concepts of Unified Modelling Language. If you recall the purpose of diagramming was to flush the
ideas early without having to worry much about the rules of a programming language or a meta language.
Often tools in the past few decades fell short in delivering that purpose.
Mermaid is a diagramming tool that needs only a notepad for you to create the diagram. In a manner of
speaking, you type code that is interpretable by Mermaid library. We believe it is no impediment to
adoption. The creators of the library capitalized on voices from past experiences with other tools. They
have kept the syntax to a minimum cognitive load and intuitive if you are thinking actively to solve a
problem and not worry about connectors and positions of elements in the diagram.
We took it to a spin to determine how easy or difficult it was. We used an online editor. You could do the
same or commission a simple HTML5 app real quick. An activity which captures our imagination for many
exercises involving exploring new shores is to pick a random GitHub repository and start applying the
experiment to the code base of that repository. We were talking about asdf in one of our earlier articles. It
was some time since our developers spent much of their time on shell scripting. It was a perfect storm as
developers wanted to understand how asdf works. There were many script files but we took the PowerShell
script version of the asdf launcher –
$Env:ASDF_DIR = $PSScriptRoot
$_asdf_bin = "$Env:ASDF_DIR/bin"
if ($null -eq $ASDF_DATA_DIR -or $ASDF_DATA_DIR -eq '') {
$_asdf_shims = "${env:HOME}/.asdf/shims"
} else {
$_asdf_shims = "$ASDF_DATA_DIR/shims"
}
$env:PATH = "${_asdf_bin}:${_asdf_shims}:${env:PATH}"
if ($env:PATH -cnotlike "*${_asdf_bin}*") {
$env:PATH = "_asdf_bin:${env:PATH}"
}
if ($env:PATH -cnotlike "*${_asdf_shims}*") {
$env:PATH = "_asdf_shims:${env:PATH}"
}
Remove-Variable -Force _asdf_bin, _asdf_shims
function asdf {
$asdf = $(Get-Command -CommandType Application asdf).Source
if ($args.Count -gt 0 -and $args[0] -eq 'shell') {
Invoke-Expression $(& $asdf 'export-shell-version' pwsh $args[1..($args.Count + -1)])
} else {
& $asdf $args
}
}
There is not much but we could visualise it as a sequence diagram which we felt adds more information
than a mere flow chart which restates the code in a visual manner.
sequenceDiagram
actor Developer
participant PowerShell Host
participant System
Developer->>+PowerShell Host: Perform initialization
PowerShell Host->>System: Set script execution directory as ASDF’s directory in environment variable
System->>PowerShell Host: Continue execution
alt Was asdf was installed in custom data directory
PowerShell Host->>PowerShell Host: Build a path variable for Shims
else
PowerShell Host->>PowerShell Host: Initialize with a default value
end
PowerShell Host->>System: Set PATH environment variables for ASDF directory, Shims directory
PowerShell Host->>PowerShell Host: Dispose variables used for Shims directory <br/> and ASDF
directory

PowerShell Host->>-Developer: Initialize a new function asdf
This produced a diagram that looks like this –

There few sleek tricks in this diagram. One of them which is easily identifiable is the one where we put text
in multiple lines with an HTML tag. We will give a breather for you to figure out what is happening. In a
different dispatch, we will circle back to describing the activity and also give you a quick preview where you
see how we integrate this diagramming plugin into a bespoke HTML5 app.