Apply suggestions from code review

Co-authored-by: Felicity Chapman <[email protected]>

Author: aeisenberg

docs/codeql/codeql-cli/about-codeql-workspaces.rst

@@ -5,18 +5,23 @@ About CodeQL Workspaces
 
 .. include:: ../reusables/beta-note-package-management.rst
 
-CodeQL workspaces are used to group multiple CodeQL packs together. A typical use case for a CodeQL workspace is for developing a set of CodeQL library and query packs that are mutually dependent. For more information on CodeQL packs, see ":doc:`About CodeQL packs <about-codeql-packs>`."
+CodeQL workspaces are used to group multiple CodeQL packs together. A typical use case for a CodeQL workspace is to develop a set of CodeQL library and query packs that are mutually dependent. For more information on CodeQL packs, see ":doc:`About CodeQL packs <about-codeql-packs>`."
 
-The main benefit of a CodeQl workspace is that it is easier to develop and maintain multiple CodeQL packs. When a CodeQL workspace is used, all CodeQL packs in the workspace are available as *source dependencies* for each other when running any CodeQL command that resolves queries. This makes it easier to develope and maintain multiple, related CodeQL packs.
+The main benefit of a CodeQL workspace is that it makes it easier for you to develop and maintain multiple CodeQL packs. When you use a CodeQL workspace, all the CodeQL packs in the workspace are available as *source dependencies* for each other when you run a CodeQL command that resolves queries. This makes it easier to develop, maintain, and publish multiple, related CodeQL packs.
 
-In most cases, the CodeQL workspace and all CodeQL packs contained in it should be stored in the same git repository so the development environment is more easily sharable.
+In most cases, you should store the CodeQL workspace and the CodeQL packs contained in it in one git repository. This makes it easier to share your CodeQL development environment.
 
-The ``codeql-workspae.yml`` file
+The ``codeql-workspace.yml`` file
 --------------------------------
 
-A CodeQL workspace is defined by a ``codeql-workspace.yml`` yaml file. This file contains a ``provide`` block, and optionally an ``ignore`` block. The ``provide`` block contains a list of glob patterns that define the CodeQL packs that are available in the workspace. The ``ignore`` block contains a list of glob patterns that define CodeQL packs that are not available in the workspace. Each entry in the ``provide`` or ``ignore`` section must map to a path to a ``qlpack.yml`` file. All glob patterns are relative to the directory containing the workspace file. See `@actions/glob <https://github.com/actions/toolkit/tree/main/packages/glob#patterns>`__ for a list of patterns accepted in this file.
+A CodeQL workspace is defined by a ``codeql-workspace.yml`` yaml file. This file contains a ``provide`` block, and optionally an ``ignore`` block. 
 
-For example, the following ``codeql-workspace.yml`` file defines a workspace that contains all CodeQL packs recursively found in the ``codeql-packs`` directory, except for the packs in the ``experimental`` directory:
+* The ``provide`` block contains a list of glob patterns that define the CodeQL packs that are available in the workspace. 
+* The ``ignore`` block contains a list of glob patterns that define CodeQL packs that are not available in the workspace. 
+
+Each entry in the ``provide`` or ``ignore`` section must map to the location of a ``qlpack.yml`` file. All glob patterns are defined relative to the directory that contains the workspace file. For a list of patterns accepted in this file, see" `@actions/glob <https://github.com/actions/toolkit/tree/main/packages/glob#patterns>`__ .
+
+For example, the following ``codeql-workspace.yml`` file defines a workspace that contains all the CodeQL packs recursively found in the ``codeql-packs`` directory, except for the packs in the ``experimental`` directory:
 
 .. code-block:: yaml
 
@@ -31,11 +36,11 @@ To verify that you have the correct ``codeql-workspace.yml`` file, run ``codeql
 CodeQL workspaces and query resolution
 --------------------------------------
 
-All CodeQL packs in a workspace are available as source dependencies for each other when running any CodeQL command that resolves queries or packs. For example, when ``codeql pack install`` is run in a pack directory in a workspace, any dependency found in the workspace will not be downloaded to the package cache, nor will it be added to the resulting ``codeql-pack.lock.yml`` file. See `:ref:Adding and Installing Dependencies <adding-and-installing-dependencies>` for more information.
+All CodeQL packs in a workspace are available as source dependencies for each other when you run any CodeQL command that resolves queries or packs. For example, when you run ``codeql pack install`` in a pack directory in a workspace, any dependency that can be found in the workspace will be instead of downloading that dependency to the package cache and adding it to the ``codeql-pack.lock.yml`` file. For more information, see `:ref:Adding and Installing Dependencies <adding-and-installing-dependencies>`__.
 
-Similarly, publishing a CodeQL query pack to the GitHub container registry using  ``codeql pack publish`` will always use dependencies found in the workspace instead of using dependencies found in the local package cache.
+Similarly, when you publish a CodeQL query pack to the GitHub container registry using  ``codeql pack publish`` the command will always use the dependencies from the workspace instead of using dependencies found in the local package cache.
 
-This ensures that any local change to a query library in a dependency in the same workspace will be automatically reflected in the published query pack.
+This ensures that any local changes you make to a query library in a dependency are automatically reflected in any query packs you publish from that workspace.
 
 .. pull-quote::
 
@@ -71,14 +76,14 @@ And the following CodeQL query pack ``qlpack.yml`` file in the workspace:
       my-company/my-library: "*"
       codeql/cpp-all: ~0.2.0
 
-Notice that, for ``my-company/my-queries``, ``"*"`` is specified as the version constraint for the library pack in the ``dependencies`` block. The library pack is defined as a source dependency in ``codeql-workspace.yml``, so the version constraint is not needed since the library pack's content is always resolved from inside of the workspace. Any version constraint will be ignored in this case, but it is recommended to use ``"*"`` for source dependencies to avoid confusion.
+Notice that the ``dependencies`` block for the CodeQL query pack,``my-company/my-queries``, specifies  ``"*"`` as the version of the library pack. Since the library pack is already defined as a source dependency in ``codeql-workspace.yml``, the library pack's content is always resolved from inside the workspace. Any version constraint you define will be ignored in this case. We recommend that you use ``"*"`` for source dependencies to make it clear that the version is inherited from the workspace.
 
-When ``codeql pack install`` is executed from the query pack directory, an appropriate version of ``codeql/cpp-all`` will be downloaded to the local package cache. Also, a ``codeql-pack.lock.yml`` file will be created that contains the resolved version of ``codeql/cpp-all``. The lock file won't contain an entry for ``my-company/my-library`` since it is resolved from source. The ``codeql-pack.lock.yml`` file will look something like this:
+When you execute ``codeql pack install`` from the query pack directory, an appropriate version of ``codeql/cpp-all`` is downloaded to the local package cache. Also, a ``codeql-pack.lock.yml`` file is created that contains the resolved version of ``codeql/cpp-all``. The lock file won't contain an entry for ``my-company/my-library`` since it is resolved from source dependencies. The ``codeql-pack.lock.yml`` file will look something like this:
 
 .. code-block:: yaml
 
    dependencies:
      codeql/cpp-all:
        version: 0.2.2
 
-When ``codeql pack publish`` is executed from the query pack directory, the ``codeql/cpp-all`` dependency from the package cache and the ``my-company/my-library`` from the workspace will be bundled with ``my-company/my-queries`` and published to the GitHub container registry.
+When you execute``codeql pack publish`` from the query pack directory, the ``codeql/cpp-all`` dependency from the package cache and the ``my-company/my-library`` from the workspace are bundled with ``my-company/my-queries`` and published to the GitHub container registry.