Diagrams as Code

I came across Diagrams as Code during a college assessment where I had to create different UML diagrams based on a given scenario. I tried different diagramming tools, such as Lucid Chart but I just did not like this method, I found it awkward and very time consuming. Then I came across diagrams as code, here I learnt that I could create diagrams using a markdown langauge, as I had already covered different aspects of coding this peaked my interest.

Diagrams as code is a simple way of creating and storing diagram images as plain text. I tried both Mermaid and PlantUML after trialling a standard diagramming tool. I will discuss each and what I liked or did not like.

Both tools can be installed through an extension on Visual Studio Code, if you are using this or through an online editor.

If you use the note taking app Notion, Mermaid is an option in the code block, where it also renders the image for you.

Mermaid benefits from its visually appealing documentation, see https://mermaid.js.org/intro/. However for me it did not work for certain diagrams I had to create for my assignment. I was expected to create a use-case diagram, among others but there was no documentation for creating use-case diagrams with Mermaid. I attempted different ways to create a use case diagram with Mermaid syntax, however it just did not suit what I wanted.

Mermaid does create many diagram types so it is beneficial for that and I cannot fault the tool, it just did not fit my needs at the time so I decided to switch to the PlantUML syntax. The documentation was also very clear with plenty of examples.

One thing to note when if installing PlantUML in Visual Studio Code is that because PlantUML is run from an online server you must in the settings either link it to your own server or link the PlantUML server provided in the extension's information, this was not a default in the settings.

Unlike Mermaid, PlantUML does not have visually appealing documentation. However, all of the information you need is there, see https://plantuml.com/. PlantUML had documentation for each diagram I had to create and more. There was a page for each diagram type and this was helpful, it also had lots of examples. I also learnt a few ne things about the diagrams I was creating.

The syntax for both diagramming tools are very similar, but they do have some simple differences. For example, PlantUML is started with "@startUML" and ended with "@endUML", whereas in Visual Studio Code Mermaid is started with "```mermaid". Otherwise, as you can see from both examples the syntax is the same for the class diagrams.

Mermaid

```mermaid

classDiagram

class BookStore{
    # AddToBasket()
}

class Account{
    # Name
    # Address
    # Phone
    # Email
    - Register()
    - Login()
}

class Book{
    # Name
    # Id
    # Description 
    # Price
}

class Basket{
    # BookId
    # BookName
    # Quantity
    # Price
    - Total()
    - Add()
    - Remove()
}

class Checkout{
    # Items
    # Quantity
    # TotalPrice
    - Details()
    - Payment()
    - Verification()
}

BookStore "1" *-- "0..*  " Account
BookStore *-- "0..*" Basket
BookStore *-- "1..*" Book
Basket "1" *-- "1 " Checkout
Book "1" o-- "0..*  " Basket
Account "1 "-->"1" Basket
Account o-- Checkout

PlantUML

@startuml classDiagram

abstract class BookStore{
    # AddToBasket()
}
class Account{
    # Name
    # Address
    # Phone
    # Email
    - Register()
    - Login()
}
class Book{
    # Name
    # Id
    # Description 
    # Price
}
class Basket{
    # BookId
    # BookName
    # Quantity
    # Price
    - Total()
    - Add()
    - Remove()
}
class Checkout{
    # Items
    # Quantity
    # TotalPrice
    - Details()
    - Payment()
    - Verification()
}

BookStore "1" *-- "0..*  " Account
BookStore *-- "0..*" Basket
BookStore *-- "1..*" Book
Basket "1" *-- "1 " Checkout
Book "1" o-- "0..*  " Basket
Account "1 "-->"1" Basket
Account o-- Checkout

@enduml

Diagrams as Code is beneficial because it is stored as plain text it provides more flexibility. It can also be very versatile for developers to read the code and understand the diagrams. It provides a feature of reusability and consistency for teams, and version control because it is stored and changed/updated in one place.