[css-animation-worklet] Explainer feedback

[domenic]

Hi @majido and others,

I did a quick pass through the explainer at https://github.com/w3c/css-houdini-drafts/blob/master/css-animationworklet/README.md and had some feedback that I thought might be helpful:

• The explainer does a great job of motivating the problem space and talking about the use cases we want to cover. It also positions itself well relative to existing solutions.

• Around the #workletanimation anchor, the explainer gets very technical, and almost spec-like. It introduces concepts in the abstract in a way that's hard for people new to the space to understand. I'd suggest instead front-loading the example code, and then explaining the code, including any of the concepts used.

• The examples assume a background understanding of the web animations API. Without this, some of the code inside new WorkletAnimation() seems pretty opaque. Why pass scrollTimeline twice? What are those KeyframeEffects doing? Perhaps a brief example without AnimationWorklet would help set the stage.

• Eventually I pieced together that most of the work is done by mutating the effect argument, but this was never stated anywhere explicitly.

• The explainer presents a coherent solution, but doesn't position it relative to any other solutions or alternatives. Were other designs considered? Were totally different primitives considered? The problems are well-stated, but how do we know this is the best solution out of the space of all possible ones?

• The example code includes various syntax errors, e.g. calling curve() instead of this.curve(), or using $scrollingContainer instead of scrollingContainer to refer to the element with that ID. These can be a bit confusing.

I hope this helps!

[majido]

This is great! Thanks for the actionable feedback and taking the time to review. I am going to spend some time addressing these.

I will start with what I think can be quickly fixed first:

• Perhaps cleaning up the examples and moving them to the top. Coincidentally I did some clean up removing some outdated information and fixing some examples yesterday but didn't catch all the mistakes.
• Give more context for how normally WebAnimation is used and add more details on how AnimationEffect is augmented to allow animation to be controlled in Animation Worklet

It may take a bit more time to include all the alternative designs that were considered but that is a good idea as well.