Document dimming of tasks outside the n=0 window

src/reference/changes.rst

@@ -85,6 +85,33 @@ Cylc 8.6.
    ``cylc config --print-hierarchy``.
 
 
+Tasks outside of the active window are dimmed
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. versionchanged:: cylc-ui 2.15.0
+
+The GUI dims (greys out) tasks to show that they are not presently being
+managed by the scheduler.
+
+Previously, only tasks in the ``none`` :term:`flow` (so called "ghost" tasks)
+were dimmed. Now, the **tree**, **table** and **graph** views dim every task
+and family that is outside of the ``n=0`` window, i.e. everything that is not
+an :term:`active task`.
+
+.. image:: ../img/dimmed-tasks.png
+   :align: center
+   :alt: Failed and running tasks fully visible while completed and waiting tasks are dimmed.
+   :width: 55%
+
+|
+
+This means that the tasks displayed at full opacity are exactly the tasks that
+Cylc is currently working on; past and future tasks pulled into the view for
+context are dimmed.
+
+See :ref:`n-window.dimming` for more information.
+
+
 Cylc 8.6
 --------
 
@@ -440,6 +467,12 @@ for something, typically:
 * An xtrigger or ext-trigger to be satisfied.
 * Someone to :term:`resume <held task>` them.
 
+.. note::
+
+   From Cylc 8.7 (``cylc-ui`` 2.15.0) this was extended so that *all* tasks
+   outside of the ``n=0`` window are dimmed, not just those in the ``none``
+   flow. See :ref:`n-window.dimming`.
+
 
 Compatibility Mode
 ^^^^^^^^^^^^^^^^^^

src/user-guide/running-workflows/tasks-jobs-ui.rst

@@ -149,3 +149,52 @@ GUI.
 
    High "graph window extent" values can cause a Cylc scheduler and the GUI
    to run slowly.
+
+
+.. _n-window.dimming:
+
+Dimmed Tasks
+^^^^^^^^^^^^
+
+.. versionchanged:: cylc-ui 2.15.0
+
+   Previously only tasks in the ``none`` :term:`flow` were dimmed. Now *all*
+   tasks outside of the ``n=0`` window are dimmed.
+
+In the GUI's **tree**, **table** and **graph** views, tasks (and families)
+which are *not* in the ``n=0`` window, i.e. those with an ``n`` value greater
+than zero, are displayed dimmed (greyed out):
+
+* Tasks shown at **full opacity** are :term:`active tasks <active task>`
+  (``n=0``). These are the tasks the scheduler is currently managing, e.g.
+  running jobs, or tasks waiting on a prerequisite, :term:`xtrigger`,
+  :term:`internal queue`, the :term:`runahead limit`, or on being
+  :term:`resumed <held task>`.
+* Tasks shown **dimmed** are :term:`inactive tasks <active task>` (``n>0``).
+  These are past or future tasks, pulled into the view to provide context.
+  The scheduler is not currently managing them, although you can still act on
+  them, e.g. by triggering them.
+
+.. image:: ../../img/dimmed-tasks.png
+   :align: center
+   :alt: Failed and running tasks fully visible while completed and waiting tasks are dimmed.
+
+|
+
+In this example (the tree view), ``eventually_succeeded``, ``succeeded`` and
+``waiting`` lie outside of the active window so are dimmed. The tasks left at
+full opacity — ``failed``, ``retrying``, ``checkpoint`` and ``sleepy`` — are
+the ``n=0`` tasks that Cylc is actively managing.
+
+This makes it easy to see, at a glance, which part of the workflow Cylc is
+actually working on.
+
+.. note::
+
+   Dimming is based on a task's position in the :term:`n-window`, not on its
+   :term:`flow numbers <flow number>`. Tasks triggered in the ``none`` flow
+   are typically outside of the ``n=0`` window, so they will usually appear
+   dimmed too. To check a task's flows, click on it and look at the
+   "Flows" field in the info view.
+
+