I saw a tweet the other day from @enjalot About using diagrams to explain code.
And was thinking what would be a good way to express such images.
Diagrams that visualised a function. The relationship to the input and output.
I am think like a flow chart or a data model. But having it interactive so that finer grained details could be express by hovering and clicking.
Still thinking on this and will update with design later on but welcome comments.
My favourite technical diagrams are:
UML Sequence charts
Good for describing time sensitive things like obtaining locks.
https://www.websequencediagrams.com/
BPMN business process models
You might be super interested in that because it supports clicking to expand the parameters on the states. Its has an XML representation too so its both machine readable, visual and executable. Its used in very boring places in non-tech companies but its pretty nice technology IMHO that has gone a few rounds of standardisation. Can model human/computer processes spanning long time horizons (e.g. submitting an insurance claim, yawn!)
UML State diagrams
Hierarchical state machines solve the state space explosion problem of finite state machines. Pretty cool but fairly narrow domain of applicability IMHO. I think they make great protocol representation.
Iām glad the thought sparked some discussion. One thing I find is that these physical diagrams are nice because the physical object is something relatable, but the abstract diagrams are hard to hold on to.
What I wonder is are there ways to make better metaphors with more physical or pictorial queues for the brain to identify concepts with?
