Dear Readers,

In this post I’d like to share my some of my thoughts on a recent discovery in diagramming and modelling, so let’s get into it right away. People working in the field of (software or any other type of) engineering probably encountered the need of creating some diagrams to be able to convey essential information about how the system is built up, how it works, etc. There are quite a few tools out there to meet such needs, and the category that really caught my attention was the “Code based tools”.

As it turns out, there are several tools out there which allow you to create UML, C4, Gantt, Git, network and other sorts of diagrams simply by typing in some code. So why is this good, one might ask? Well, here are some reasons I could think of at the moment:

  • being able to treat diagrams just like any other code
  • not needing to worry about diagram layout much, as diagrams are auto-generated
  • diagrams (and the skills needed to produce them) are a highly transferrable, as code is not restricted to any one tool
  • one can fully concentrate on the creating the content without needing to wrestle with the tool
  • the storage format has very high “business information” concentration, yet it is both machine and human readable
  • having basic scripting capabilities (loops, if statements) to speed diagram generation up

As there are several languages and tools one can choose from, one has to decide which one suits best based on some attributes: Some of the tools are just for diagramming, some others support modelling as well; some are available free of charge, some others require monthly subscription; some tools can be run locally, some others are online tools, etc. Because I wanted to just jump in and try this sort of thing out, I ended up playing around with PlantUML in combination with VS Code and a corresponding extension, as it supports live preview and simple export of the coded diagrams.

Of course, just as any other tool out there, these ones are not without downsides either. One of them is that not all UML diagram types are supported, although this might not be a real problem, as the most commonly used are available. One strength of code-based diagrams can be a downside as well (namely that diagrams are auto-generated), as diagram objects cannot be manually rearranged (although syntax for altering the auto-generated position exists, but this only gives very limited position control), which is not a problem on simple diagrams, but could be a real issue with more complicated ones.

Other than these, I found such code-based diagramming rather productive so far, as I can really concentrate on the actual content without needing to wrestle with the GUI of a graphical tool. If this sort of diagramming will hold up in the long run, we’ll see. Until then, thanks for reading.