Hi HN, I struggle documenting complex distributed algorithms. Sequence diagrams are great for precision, but you end up with the prose on one page, explaining each step, and the reference diagram elsewhere, which is really hard to read. The readers eyes have to go back and forth long distances.
This notebook is my revelation of using interaction to limit the prose and to highlight the active step on a sequence diagram. This seems to aid in readability for me a lot.
Cool. The code might look scary but it's intuitive. The mermaid diagram lib is preinstalled in Observable notebooks. The diagrams can be created with the template literal mermaid``.
A range input is set up, which returns the number at which the slider or text input is set. This immediately dispatches on any changes.
The diagram cell takes advantage of this reactive dispatching. It passes the result of a chain of ternary clauses, almost like a switch statement.
The cool thing is that you can approach this in a few other ways. You can access an array item if you use the range output as a computed array index, the returned item will correspond with the number set in the range input. Tom added that example as well, in the cell above the diagram cell.
Finally, he mentioned that the user can move the animation at their own pace. That means, using the included Promises lib (not 'Promise', that's a JS module), you can use the .interval or .tick methods to yield a new value at every x msecs. Now instead of having the animation hooked up to the manual range input, you hook it up to the tick method and you've got yourself the basis of a slideshow.
Try it. Just start editing the code, and a copy is automatically made for you to fork. Yes, you can do pull requests on notebooks!
I've made a few diagrams from code over the years using graphviz, draw.io, debugmode wink, plantuml to show a logical or physical software architecture.
Yet I have only been able to animate data flowing through any of these systems by recording myself drawing on a PowerPoint and having that play back as a video.
Does anyone know if there is a way to create offline animations of these tools, including the ability to have steps with explanations of what's going on at each step? (preferably in code)
Besides my poor man's video files, I'm mostly only aware of traditional animation tools or these software as service subscriptions.
Observable is an IDE. It is code. You can definitely use it to generate GIFs [1] and whatnot too. So it's possible to build what you want, but you need to roll your sleeves up :/
This notebook is my revelation of using interaction to limit the prose and to highlight the active step on a sequence diagram. This seems to aid in readability for me a lot.