Dynamic Diagrams

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.

Content:

• Existing solutions
• A new simple language for interactive 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:

1. 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.

2. 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.

3. 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

Personally, I’ve always been a fan of ⊕ Mermaid is a JavaScript based diagramming and charting tool that renders Markdown-inspired text definitions to create and modify diagrams dynamically. MermaidJS. Like many developers, I appreciate how text-based diagram generators strip away much of the complexity associated with visual tools like Inkscape or or diagrams.net. Text based tools like MermaidJS, have garnered widespread appreciation for their simplicity and effectiveness. The real charm lies in their ability to convert short, concise text into elaborate diagrams. This textual approach not only makes diagram creation easier but also integrates seamlessly with version control systems, maintaining clear semantics across multiple commits. If you’re documentation lives as Markdown files on Github you can embed your diagrams without the need to include any additional tools.

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 elements.

<liquid-diagram style="display: block">
add "A"
  pos -10 -7
  size 20 15
add "B"
  pos -35 -35
  size 20 15
|- then -|
connect "A" "B" "A to B"
</liquid-diagram>

<script src="/assets/js/liquid-diagrams.js"></script>