[amitp]

Having been down this road, yes, it does take time, but you can save some time by using SVG and some DOM library. Although canvas is faster, most diagrams don't really need it, so I use SVG unless I really need to switch to canvas. SVG also adjusts for screen dpi automatically.

The things I like:

1. Reactivity (ObservableHQ, Vue.js, hyperactiv.js, etc.). There's usually some underlying data and then a corresponding visualization. These reactive systems let you modify the underlying data and then the visualization updates automatically. You don't have to figure out which diagrams to update when. Even easier: just redraw everything every time you change anything.

2. Some easier way to write the DOM (d3.js, jsx, vue, lit-html, etc.). Since I'm writing a blog post with html, I usually prefer writing my js-in-html (vue) rather than html-in-js (jsx) but try both directions and see which you prefer.

3. No build step. This is especially important when I want to update a page years later and don't want to figure out which build tools I was using in 1997 or 2007 or 2017. I want my pages to last for decades, and I still update my pages from 25 years ago.

I tried recreating one of the gear page diagrams in ObservableHQ https://observablehq.com/@redblobgames/unwind-circle-example . It's not a lot of code. There's a slider, there's a loop to generate the lines, and there's the output svg. Whenever you move the slider it recalculates the output.

I admit that I'm not using ObservableHQ much for my own projects because I want more of a "hand-written" style. I used d3.js for my older pages and vue.js for my newer pages. Vue's reactivity and templates save me probably a factor of 2 or 3 over d3.js.

[chubot]

Thanks for these tips -- I've seen your visualizations and it's nice to hear from people who have done it!

It's cool that you were able to reproduce the diagram quickly and in a small amount of code. It looks a bit foreign to me, probably because I don't know much about SVG (or canvas for that matter). And as I understand it Observable is almost another language on top. (I do know HTML, CSS, and JS pretty well, but there's still a gap.)

Do you ever mock visualizations up in a WYSIWIG tool, or do you always use web technologies in a text editor?

Doing it programmatically has advantages when you need to make 30 similar diagrams, as in this post about gears.

But I also feel WYSIWIG tools could help in prototyping to avoid throwing away a lot of code that wasn't properly conceived of. That is, implementing the visualization is only part of the huge amount of work; the other part is designing it of course. And in many cases the design effort is probably larger.

For example, I have wanted to write an article about regexes, visualizing NFAs and DFAs. I find that some programmers have trouble with the idea of nondeterminism, which is more of a mathematical thing. A subtitle would be something like "A trie is a special case of a DFA".

This post has some nice diagrams, and you can easily imagine them being interactive and more approachable:

https://swtch.com/~rsc/regexp/regexp1.html

(in fact a few months ago else I posited that a textual summary of these great but dense posts would be useful too)

I can sort of imagine what I want to visualize, but I also think there will also be many false starts. Though maybe a pencil and paper is sufficient. I'm not sure I will get to it, but this polished and smooth gears post got me thinking again! Using something reactive like vue rather than doing it "vanilla JS" is also probably something I should look into as well.

[amitp]

SVG is declarative. You write <circle cx=300 cy=400 r=100 fill=red/> to make a red circle at (300,400) with radius 100. You can then change any of these properties and the system will redraw automatically. Canvas is imperative. You write ctx = canvas.getContext('2d'); ctx.fillStyle = "red"; ctx.beginPath(); ctx.arc(300, 400, 100, 0, 2 * Math.PI); ctx.fill(); and the system will draw that circle. You handle redraw yourself by redrawing everything on that canvas, so you need to keep track of it all. The DOM helpers (React, Vue, etc.) help you with SVG but not with Canvas.

I usually mock visualizations on paper! I'm interested in using WYSIWIG interactive diagram tools like http://aprt.us/ but I never seem to get into them. When I started, making the visualizations was the largest part of the work, but now I've gotten better at it, and making the explanation is now the part that takes the most time.

After paper, I often use SVG to make a non interactive diagram, either by hand, or in inkscape. One of my guiding principles is that the page should be usable without interaction, so the static diagram is a test of that. If it looks promising I can then gradually transform it into an interactive diagram. For example if I had the circle above, and I am using vue.js, I can change it to <circle :cx=x :cy=y r=100 fill=red/> (note the ":" before attributes), and then vue will fill those values in from the object I give it. I can give it {x: 300, y: 400}, and any time I change x or y, it will automatically redraw. I can then hook up x or y to a slider to try out the interactivity. This allows me to start with a static diagram, gradually add interactivity, and then build reusable abstractions that I can apply to multiple diagrams. ObservableHQ and React/JSX allow something similar, with slightly different syntax.

I'd love to see an article about regexes with interactive diagrams. There's a standalone diagram tool https://regexper.com/ and an interactive tutorial https://regexone.com/ but neither is an essay in the style of the Gears article. If you're pursuing this, let me know at [e-mail] and I can send over more resources.

[TeMPOraL]

Observable is amazing! Some time ago, I prototyped half of the 2.0 version of a company's product in it in a scope of a few days; that's how nicely the notebook interface and reactive programming fit together.

I didn't realize Vue can work without a build step; that's actually great. While I so far avoided using any JS on my tiny little blog, I'd really like to do some interactive explanations. I'll check this workflow out. Thanks!

Last but not least, I'm a great fan of your articles! Keep up the great work!

[spankalee]

Observable's templating is directly inspired by lit-html, which also works without a built step, and works great with SVG.

[kragen]

Thanks for sharing these tips! I didn't realize you were trying out ObservableHQ too.

[amitp]

I love ObservableHQ! I think it's a neat model that fixes a lot of things I didn't like about notebooks. I don't use it much though. It makes the simple things easier but it makes the complex things harder. Examples:

1. I often start making a diagram interactive by adding a slider connected to some state. The slider/state is in one "viewof" cell and the diagram is in another cell. But for more polished work I often want to use direct manipulation, where you move something around in the diagram itself. In my usual JS+Vue code it's a small amount of extra work. But in ObservableHQ it seems like a lot of work: the diagram has to modify state defined in a different cell (breaking the simple spreadsheet model in my head), and the diagram is being re-rendered while it has event handlers active.

2. I often start out by making one diagram. This is nice and easy. But then I want to make multiple diagrams with some shared state. In my usual JS+Vue code I can lift the diagram code into a function, pass in a shared object for shared state, and instantiate objects for non-shared state. In ObservableHQ those properties are in cells, and I can't generate multiple cells programatically (afaik).

I also would prefer to host things myself, both because of longevity, but also because I sometimes work offline (e.g. in a park or on a train). And the biggest reason I'm not using ObservableHQ is that I'm so much slower editing text on it than I am in Emacs. So I continue to use ObservableHQ for some simple projects/prototypes but I don't do a lot with it.

[kragen]

Yeah, the centralization aspect is a big turnoff for me. I'd thought about the direct-manipulation issue (the rather crude visualization of skeletonization I linked below benefits a lot from it) but not the multiple-projections problem. Can't you put the entire state in one cell and then create multiple cells that render some reduced dimensionality projection of it? Or do you mean that there's no way to factor out the aggregation of three such projections into a reusable unit?

I recently walked my girlfriend through your explorable on populating landscapes with Perlin noise btw. It was great.