I think this is a great in-depth answer to the question you mention in the beginning (“why is Json.Decode so confusing?”), and also does a great job of showing the logical process to arrive at the API.
The one suggestion I’d have is that the article is quite long–does dev.to have a way to add a table of contents?
Also, I’m curious if there were other APIs for this that you originally tried to implement which you initially thought might be a nicer API but weren’t possible to implement. If so, I’d be interested to see a small section showing why some of those things didn’t work (or maybe in a future blog post).