Review of User Guides section (#1663)

* Review of User Guides section

* Update docs/doc_sources/user_guides/environment_variables.rst

Co-authored-by: ndgrigorian <[email protected]>

* Update docs/doc_sources/user_guides/basic_concepts.rst

Co-authored-by: Oleksandr Pavlyk <[email protected]>

* Update execution_model.rst

* Update docs/doc_sources/user_guides/execution_model.rst

Co-authored-by: Oleksandr Pavlyk <[email protected]>

---------

Co-authored-by: ndgrigorian <[email protected]>
Co-authored-by: Oleksandr Pavlyk <[email protected]>

Author: 3 people

docs/doc_sources/user_guides/basic_concepts.rst

@@ -168,7 +168,7 @@ they do not compare equal, since they correspond to two independent scheduling e
 Event
 -----
 
-SYCL event is an entity created when a task is submitted to SYCL queue for execution. The event are be used to
+A SYCL event is an entity created when a task is submitted to SYCL queue for execution. The events are used to
 order execution of computational tasks by the DPC++ runtime. They may also contain profiling information associated
 with the submitted task, provided the queue was created with "enable_profiling" property.
 
@@ -196,7 +196,7 @@ queue. This queue argument is stored the instance of the class and is used to su
 tasks to when performing copying of elements from or to this allocation or when filling
 the allocation with values.
 
-Classes that represent host-accessible USM allocations, i.e. types USM-shared and USM-host,
+Classes that represent host-accessible USM allocations, i.e., types USM-shared and USM-host,
 expose Python buffer interface.
 
 .. code-block:: python
@@ -224,7 +224,7 @@ Backend
 
 Intel(R) oneAPI Data Parallel C++ compiler ships with two backends:
 
-#. OpenCL backend
+#. OpenCL* backend
 #. Level-Zero backend
 
 Additional backends can be added to the compiler by installing CodePlay's plugins:

docs/doc_sources/user_guides/environment_variables.rst

@@ -18,13 +18,13 @@ description and :ref:`uses <beginners_guide_oneapi_device_selector_usecase>`.
 Variable ``SYCL_CACHE_PERSISTENT``
 ----------------------------------
 
-The binaries implementing :py:mod:`dpctl.tensor` created using DPC++ compiler contain sections
-with standardized intermediate forms (e.g. `SPIR-V <https://www.khronos.org/spir/>`_) that must be
+The binaries implementing :py:mod:`dpctl.tensor` created using the DPC++ compiler contain sections
+with standardized intermediate forms (e.g., `SPIR-V <https://www.khronos.org/spir/>`_) that must be
 further built using SYCL device drivers for execution on the specific target hardware.
 This step is known as just-in-time compiling (JIT-ing).
 
-By default, the result of JIT-ing persists for the duration of SYCL application, i.e. for the
-duration of the Python session where :py:mod:`dpctl.tensor` is used. Setting environment variable
+By default, the result of JIT-ing persists for the duration of SYCL application, i.e., for the
+duration of the Python session where :py:mod:`dpctl.tensor` is used. Setting the environment variable
 ``SYCL_CACHE_PERSISTENT`` to value of ``1`` instructs DPC++ runtime to save the result of JIT-ing to
 disk and reuse it in subsequent Python sessions (assuming the variable remains to be set when sessions
 are started).
@@ -37,7 +37,7 @@ Variable ``SYCL_PI_TRACE``
 --------------------------
 
 Setting this debugging variable enables specific levels of tracing for SYCL Programming Interfaces (PI).
-The value of the variable is a bit-mask, with the following supported values
+The value of the variable is a bit-mask, with the following supported values:
 
 .. list-table::
     :header-rows: 1

docs/doc_sources/user_guides/execution_model.rst

@@ -8,7 +8,7 @@ oneAPI library and its Python interface
 =======================================
 
 Using oneAPI libraries, a user calls functions that take ``sycl::queue`` and a collection of
-``sycl::event`` objects among other arguments, e.g.
+``sycl::event`` objects among other arguments. For example:
 
 .. code-block:: cpp
     :caption: Prototypical call signature of oneMKL function
@@ -27,7 +27,7 @@ vector complete. If the vector is empty, the runtime begins the execution as soo
 ready. The function returns a ``sycl::event`` object representing completion of the set of
 computational tasks submitted by the ``compute`` function.
 
-Hence, in oneAPI programming model, the execution **queue** is used to specify which device the
+Hence, in the oneAPI programming model, the execution **queue** is used to specify which device the
 function will execute on. To create a queue, one must specify a device to target.
 
 In :mod:`dpctl`, the ``sycl::queue`` is represented by :class:`dpctl.SyclQueue` Python type,
@@ -42,8 +42,9 @@ and a Python API to call such a function might look like
     ) -> dpctl.SyclEvent:
         ...
 
-Even if Python API to an offloading Python function looks different from this, it must
-translate to a similar call under the hood.
+When building Python API for a SYCL offloading function, and you choose to
+map the SYCL API to a different API on the Python side, it must still translate to a
+similar call under the hood.
 
 The arguments to the function must be suitable for use in the offloading functions.
 Typically these are Python scalars, or objects representing USM allocations, such as
@@ -74,7 +75,7 @@ with the queue are used to make the allocation.
     Python type representing the USM allocation.
 
 This design choice allows :mod:`dpctl` to have a preferred queue to use when operating on any single
-USM allocation, i.e.
+USM allocation. For example:
 
 .. code-block:: python
 
@@ -141,7 +142,7 @@ can be combined together in accordance with compute-follows-data programming mod
     >>> # rules are not met
     >>> tensor.concat((y1, y2))
 
-Please refer to :ref:`array migration <dpctl_tensor_array_migration>` section of the introduction to
+Please refer to the :ref:`array migration <dpctl_tensor_array_migration>` section of the introduction to
 :mod:`dpctl.tensor` to examples on how to resolve ``ExecutionPlacementError`` exceptions.
 
 ..