cr: mmocny

spec/patches.md

@@ -64,16 +64,16 @@ most scheduling flexibility.
 But the intent of this specification is that the {{TaskPriority}} of {{Scheduler}} tasks would
 influence the event loop priority. Specifically, "{{TaskPriority/background}}" tasks and
 continuations are typically considered less important than most other event loop tasks, and
-"{{TaskPriority/user-blocking}}" tasks and "{{TaskPriority/user-visible}}" and
-"{{TaskPriority/user-blocking}}" continuations are typically considered to be more important.
+"{{TaskPriority/user-blocking}}" tasks and continuations, as well as "{{TaskPriority/user-visible}}"
+continuations (but not tasks), are typically considered to be more important.
 <br/><br/>
 One strategy is to run {{Scheduler}} tasks with an [=scheduler task queue/effective priority=] of 3
 or higher with an elevated priority, e.g. lower than input, rendering, and other <em>urgent</em>
 work, but higher than most other [=task sources=]. {{Scheduler}} tasks with an [=scheduler task
-queue/effective priority=] of 0 or 1 ("{{TaskPriority/background}}") could be run only when no other
-tasks in an [=event loop=]'s [=task queues=] are [=task/runnable=], and {{Scheduler}} tasks with an
-[=scheduler task queue/effective priority=] of 2 ("{{TaskPriority/user-visible}}" tasks) could be
-scheduled like other scheduling-related [=task sources=], e.g. the [=timer task source=].
+queue/effective priority=] of 0 or 1 could be run only when no other tasks in an [=event loop=]'s
+[=task queues=] are [=task/runnable=], and {{Scheduler}} tasks with an [=scheduler task
+queue/effective priority=] of 2 could be scheduled like other scheduling-related [=task sources=],
+e.g. the [=timer task source=].
 
 Issue: The |taskQueue| in this step will either be a [=set=] of [=tasks=] or a [=set=] of
 [=scheduler tasks=]. The steps that follow only [=set/remove=] an [=set/item=], so they are

spec/scheduling-tasks.md

@@ -16,15 +16,23 @@ This spec formalizes three priorities to support scheduling tasks:
 tasks that should run as soon as possible, such that running them at a lower priority would degrade
 user experience. This could be (chunked) work that is directly in response to user input, or
 updating the in-viewport UI state, for example.
+<br/><br/>
+Note that tasks scheduled with this priority will typically have a higher event loop priority
+compared to other tasks, but they are not necessarily render-blocking. Work that needs to happen
+immediately without interruption should typically be done synchronously &mdash; but this can lead to
+poor responsiveness if the work takes too long. "{{TaskPriority/user-blocking}}" tasks, on the other
+hand, can be used to break up work and remain remain responsive to input and rendering, while
+increasing the liklihood that the work finishes as soon as possible.
 
 <dfn enum-value for=TaskPriority>user-visible</dfn> is the second highest priority, and it is meant
-for tasks that will be visible to the user, but either not immediately or are not essential to user
-experience. These tasks are either less important or less urgent than user-blocking tasks. This is
-the default priority.
+for tasks that will have useful side effects that are observable to the user, but either which are
+not immediately observable or which are not essential to user experience. Tasks with this prioriy
+are less important or less urgent than "{{TaskPriority/user-blocking}}" tasks. This is the default
+priority.
 
 <dfn enum-value for=TaskPriority>background</dfn> is the lowest priority, and it is meant to be used
-for tasks that are not time-critical, such as background log processing or initializing certain
-third party libraries.
+for tasks that are not time-critical, such as background log or metrics processing or initializing
+certain third party libraries.
 
 Continuation priorities mirror task priorities, with an additional option to inherit the current
 priority: