Analytically Speaking

A picture tells a thousand words and as business analysts, it becomes important for us to do just that, to stakeholders needing a birds eye view and those needing a more granular view into how things do and should work. I remember first learning how to use diagramming tools that require a drag and drop of elements and being quite frustrated with the lines crossing over each other or not being straight with the time ticking for needing to get things done. Discovering declarative diagramming tools has been a game changer and time saver. But what is declarative diagramming? It is essentially the ability to create diagrams through plain text – which could look like writing some code to generate pictures. There are several declarative diagramming tools available and a browser search will return these three as the top results:

1. D2
2. Mermaid
3. PlantUML

I have not used D2 but I have widely used Mermaid and PlantUML. From playing around with D2, it seems that there is much more that is possible from declaring shapes and their dimensions and with Mermaid and PlantUML, there are several diagram types that you can create without creating shapes from scratch. Access to the declarative diagramming tools is also something to consider when deciding which one would work for you. The table below compares the ease of access for each of the tools:

With the table above, it may be clear that the most accessible or easiest to use are both Mermaid and PlantUML. It is worth noting that when using a web browser version to access the tool, there are security concerns regarding exposing sensitive data and with Mermaid, certain features are behind a pay wall. Using a code editor like VSCode to access the tools seems to be the easiest route as they are available for install as extensions. Another thing to consider is the use of AI with this tooling. When using something like VSCode, whilst having GitHub Copilot installed, it is possible to use it as an assistant, further to that the AI LLMs that exist do allow for prompting that can return script for each of the tools. However, it is ideal to know how to write the code for each tool so that correction becomes less prompt heavy. Whilst AI can save time for all sorts of things, it helps to know how to use the tooling without it, especially where information security is a concern. But now that it is known how to access them, it becomes necessary to see what each tool offers as far as diagrams that can be created. Each tool has a specialty and diagrams can be for systems and architectural design or project planning – including the people aspect. The table below shows what each tool gives in terms of diagrams you can create with it. It also indicates which tools create certain diagrams well as *star diagram*: