Static images, videos, and SVG animations come each with their own challenges when it comes to visualize complex systems through diagrams. I’ve developed a mini language and web component to add a narrative element to diagrams.
Technical documentation is an essential component for explaining complex systems. To effectively represent the relationships between system components, diagrams have become a staple. However, as systems grow in complexity, so do their diagrams, often leading to representations that are complicated and challenging to follow. Additionally, capturing changes over time in static diagrams presents a significant hurdle.
You can yog through the different states of the diagram using the arrow buttons ⬅ ➡ or the slider.
With the ✏️ button you can view and update the source of the diagram.
Current Solutions and Their Limitations
Currently, there are a few approaches to address these issues:
Multiple Static Images: Breaking down evolving diagrams into several static images is common. However, this method can be cumbersome, as it forces readers to scroll up and down to reference different stages of the diagram.
Video Format: Using videos to animate diagrams adds a dynamic aspect, making it easier to understand changes over time. But video production demands specific skills and often results in large file sizes, which is not ideal for quick loading web documentation.
SVG Animations: SVG, combined with CSS and JS animations, is another method to create dynamic diagrams. While promising, this approach requires technical writers to have specific skills and potentially expensive tools.
A new simple language for interactive diagrams
Most times, when I set out to create a diagram, I find myself needing just a few boxes connected by arrows. However, I’ve always yearned for a way to narrate a story through my diagrams, to gradually introduce elements like boxes and arrows rather than presenting everything all at once. This led me to develop a new language and web component that accomplishes exactly this. With my tool, you can easily build your narrative, adding elements to your diagram step by step, making the complex information more digestible and engaging.
If you want to try it out feel free to download the webcomponent.
Include it at the end of your HTML document after you’ve specified your
<liquid-diagram style="display: block">
pos -10 -7
size 20 15
pos -35 -35
size 20 15
|- then -|
connect "A" "B" "A to B"