[css-view-transitions-1][editorial] Minor tweaks to API prose

Author: fantasai

css-view-transitions-1/Overview.bs

@@ -884,19 +884,24 @@ urlPrefix: https://wicg.github.io/navigation-api/; type: interface;
 
 	<dl class="domintro non-normative">
 		: <code>{{ViewTransition|viewTransition}} = {{Document|document}}.{{startViewTransition}}({{UpdateCallback|updateCallback}})</code>
-		:: Starts a new view transition.
+		:: Starts a new [=view transition=]
+			(canceling the {{Document|document}}’s existing [=active view transition=], if any).
 
 			{{UpdateCallback|updateCallback}} is called asynchronously, once the current state of the document is captured.
-			Then, when the promise returned by {{UpdateCallback|updateCallback}} fulfills, the new state of the document is captured.
+			Then, when the promise returned by {{UpdateCallback|updateCallback}} fulfills,
+			the new state of the document is captured
+			and the transition is initiated.
 
-			{{UpdateCallback|updateCallback}} is *always* called, even if the transition cannot happen (e.g. due to duplicate `view-transition-name` values).
+			Note that {{UpdateCallback|updateCallback}} is *always* called,
+			even if the transition cannot happen
+			(e.g. due to duplicate `view-transition-name` values).
 			The transition is an enhancement around the state change, so a failure to create a transition never prevents the state change.
 			See [[#transitions-as-enhancements]] for more details on this principle.
 
 			If the promise returned by {{UpdateCallback|updateCallback}} rejects, the transition is skipped.
 	</dl>
 
-### {{Document/startViewTransition()}} ### {#ViewTransition-prepare}
+### {{Document/startViewTransition()}} Method Steps ### {#ViewTransition-prepare}
 
 	<div algorithm>
 		The [=method steps=] for <dfn method for=Document>startViewTransition(|updateCallback|)</dfn> are as follows:
@@ -908,16 +913,19 @@ urlPrefix: https://wicg.github.io/navigation-api/; type: interface;
 		1. Let |document| be [=this's=] [=relevant global object's=] [=associated document=].
 
 		1. If |document|'s [=active view transition=] is not null,
-			then [=skip the view transition=] |document|'s [=active view transition=]
+			then [=skip the view transition|skip that view transition=]
 			with an "{{AbortError}}" {{DOMException}} in [=this's=] [=relevant Realm=].
 
-			Note: This can result in two asynchronous [=ViewTransition/update callbacks=] running concurrently.
-			One for the |document|'s current [=active view transition=], and another for this |transition|.
+			Note: This can result in two asynchronous [=ViewTransition/update callbacks=] running concurrently
+			(and therefore possibly out of sequence):
+			one for the |document|'s current [=active view transition=], and another for this |transition|.
 			As per the [design of this feature](#transitions-as-enhancements), it's assumed that the developer is using another feature or framework to correctly schedule these DOM changes.
 
 		1. Set |document|'s [=active view transition=] to |transition|.
 
-			Note: The process continues in [=setup view transition=], via [=perform pending transition operations=], which is called in [[#monkey-patch-to-rendering-algorithm]].
+			Note: The [=view transition=] process continues in [=setup view transition=],
+			via [=perform pending transition operations=],
+			which is called in [[#monkey-patch-to-rendering-algorithm]].
 
 		1. Return |transition|.
 	</div>
@@ -934,15 +942,15 @@ urlPrefix: https://wicg.github.io/navigation-api/; type: interface;
 		};
 	</xmp>
 
-	Note: The {{ViewTransition}} represents and controls a single same-document transition.
-	That is, it controls a transition where the starting and ending document are the same,
+	The {{ViewTransition}} interface represents and controls a single same-document [=view transition=],
+	i.e. a transition where the starting and ending document are the same,
 	possibly with changes to the document's DOM structure.
 
 	<dl class="domintro non-normative">
 		: <code>{{ViewTransition|viewTransition}}.{{ViewTransition/updateCallbackDone}}</code>
 		:: A promise that fulfills when the promise returned by {{UpdateCallback|updateCallback}} fulfills, or rejects when it rejects.
 
-			The View Transition API wraps a DOM change and creates a transition.
+			Note: The View Transition API wraps a DOM change and creates a visual transition.
 			However, sometimes you don't care about the success/failure of the transition animation,
 			you just want to know if and when the DOM change happens.
 			{{ViewTransition/updateCallbackDone}} is for that use-case.
@@ -955,22 +963,27 @@ urlPrefix: https://wicg.github.io/navigation-api/; type: interface;
 			This can be due to misconfiguration, such as duplicate 'view-transition-name's,
 			or if {{ViewTransition/updateCallbackDone}} returns a rejected promise.
 
-			The point that {{ViewTransition/ready}} fulfills is the ideal opportunity to animate the view transition pseudo-elements with the [[web-animations-1#extensions-to-the-element-interface|web animation API]].
+			The point that {{ViewTransition/ready}} fulfills
+			is the ideal opportunity to animate the [=view transition pseudo-elements=]
+			with the [[web-animations-1#extensions-to-the-element-interface|Web Animation API]].
 
 		: <code>{{ViewTransition|viewTransition}}.{{ViewTransition/finished}}</code>
 		:: A promise that fulfills once the end state is fully visible and interactive to the user.
 
 			It only rejects if {{UpdateCallback|updateCallback}} returns a rejected promise,
 			as this indicates the end state wasn't created.
 
-			Otherwise, if a transition fails to begin, or is skipped (from skipTransition()), the end state is still reached,
+			Otherwise, if a transition fails to begin,
+			or is skipped (by {{ViewTransition/skipTransition()}}),
+			the end state is still reached,
 			so {{ViewTransition/finished}} fulfills.
 
 		: <code>{{ViewTransition|viewTransition}}.{{ViewTransition/skipTransition}}()</code>
 		:: Immediately finish the transition, or prevent it starting.
 
 			This never prevents {{UpdateCallback|updateCallback}} being called,
-			as the DOM change is separate to the transition. See [[#transitions-as-enhancements]] for more details on this principle.
+			as the DOM change is independent of the transition.
+			See [[#transitions-as-enhancements]] for more details on this principle.
 
 			If this is called before {{ViewTransition/ready}} resolves, {{ViewTransition/ready}} will reject.
 
@@ -1038,7 +1051,7 @@ urlPrefix: https://wicg.github.io/navigation-api/; type: interface;
 
 	The {{ViewTransition/updateCallbackDone}} [=getter steps=] are to return [=this's=] [=ViewTransition/update callback done promise=].
 
-	### {{ViewTransition/skipTransition()}} ### {#ViewTransition-skipTransition}
+### {{ViewTransition/skipTransition()}} Method Steps ### {#ViewTransition-skipTransition}
 
 	<div algorithm>
 		The [=method steps=] for <dfn method for="ViewTransition">skipTransition()</dfn> are: