[css-view-transitions-1] Improve spec readability

[annevk]

View Transitions is a set of API that allow DOM changes to smoothly animate between states.

APIs*

But what I'm reading in the explainer is that it's a way to animate across a lot of node tree mutations at once.

cc @jakearchibald

[jakearchibald]

I'm going to take a pass on the spec and add loads of non-normative stuff to hopefully improve readability.

But what I'm reading in the explainer is that it's a way to animate across a lot of node tree mutations at once.

Couldn't they be said to be two different states? Two states can differ by many tree differences, style differences etc etc.

[annevk]

Thanks!

What is the state of a "DOM change"? I think you can say that a node tree is in a particular state, sure, though this is not something the DOM standard does. The DOM doesn't directly store all style information so I'm not sure that would be captured.

[jakearchibald]

Feels like the same root issue as #8144

[annevk]

Partially, but I think the wording is confusing as well. I don't think you can say that a change has state.

[jakearchibald]

Maybe we're reading the word 'state' differently.

The intent here is that the document is in a particular state. Then a change is made, resulting in the document being in some different state.

So, the document has undergone a "state change". The 'update' created the difference between those states by altering the tree/styles/etc.

Feels like, here and #8144, we're looking for a word that communicates that the document model/style can change in a way that will result in a visual change, and that it was in some state/form/shape/structure before, and now it's in some different state/form/shape/structure.

[annevk]

I understand the intent, but reading that sentence it doesn't convey that to me.

The sentence suggests it's an API that allows DOM changes to do something. What can DOM changes do? They can animate between states. But that's not what this is. DOM changes cannot do anything.

[jakearchibald]

Ahh ok, I think I get it now.

So instead of:

View Transitions is a set of API that allow DOM changes to smoothly animate between states.

It could be:

View Transitions is a set of API that create animations for changes in document state.

[annevk]

Yeah, that looks good. Was struggling myself to come up with that wording.

[jakearchibald]

I'll look out for other stuff like that as I update it for readability. That section in particular will change a lot.

[jakearchibald]

Renaming this to capture a wider job of improving spec readability via:

• More detailed intro, detailing phases of a transition. Include links to 'entry points', as in where the process starts.
• Include a note at the start of each algorithm / section, summarising its purpose (unless it's really obvious)
• Add domintro sections for the API
• Add diagrams to other sections where appropriate

[jakearchibald]

I think this is complete. @annevk does it look better to you?

• Revamped intro including high-level lifecycle, and video examples.
• Improved non-normative sections throughout, including domintro sections, and diagrams.
• Reviewed naming and grouping of algorithms.

[khushalsagar]

Friendly ping @annevk. Just checking if there is more work to be done here or we can close the issue.

[annevk]

I think this can be closed, yeah. In particular given #8574.