Further changes from the technical review

Author: felicitymay

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

@@ -21,7 +21,7 @@ You can use the CodeQL package manger in the CodeQL CLI to create CodeQL packs,
 CodeQL pack structure
 ---------------------
 
-A CodeQL pack must contain a file called ``qlpack.yml`` in its root directory. In the ``qlpack.yml`` file, the ``name:`` field must have a value that follows the format of ``<scope>/<pack>``, where ``<scope>`` is the GitHub organization that the pack is published to and ``<pack>`` is the name of the pack. The other
+A CodeQL pack must contain a file called ``qlpack.yml`` in its root directory. In the ``qlpack.yml`` file, the ``name:`` field must have a value that follows the format of ``<scope>/<pack>``, where ``<scope>`` is the GitHub organization or user account that the pack will be published to and ``<pack>`` is the name of the pack. The other
 files and directories within the pack should be logically organized. For example, typically:
 
 - Queries are organized into directories for specific categories.
@@ -31,7 +31,11 @@ files and directories within the pack should be logically organized. For example
 About ``qlpack.yml`` files
 --------------------------
 
-When executing query-related commands, CodeQL first looks in the package cache for CodeQL packs which have already been downloaded. If a suitable pack cannot be found, then CodeQL scans siblings of the installation directory (and their subdirectories) for ``qlpack.yml`` files. The metadata in each `qlpack.yml`` file tells
+When executing query-related commands, CodeQL first looks in siblings of the installation directory (and their subdirectories) for ``qlpack.yml`` files. 
+Then it checks the package cache for CodeQL packs which have been downloaded. This means that when you are developing queries locally, the local packages 
+in the installation directory override packages of the same name in the package cache, so that you can test your local changes.
+
+The metadata in each `qlpack.yml`` file tells
 CodeQL how to compile any queries in the pack, what libraries the pack depends on, and where to
 find query suite definitions.
 
@@ -65,11 +69,11 @@ The following properties are supported in ``qlpack.yml`` files.
    * - ``version``
      - ``0.0.0``
      - All packs
-     - A version number for this CodeQL pack. This must be a valid semantic version that meets the `SemVer v2.0.0 specification <https://semver.org/spec/v2.0.0.html>`__.
+     - A version range for this CodeQL pack. This must be a valid semantic version that meets the `SemVer v2.0.0 specification <https://semver.org/spec/v2.0.0.html>`__.
    * - ``dependencies``
      - ``codeql/javascript-all: ^1.2.3``
      - Optional
-     - The names of any CodeQL packs that this pack depends on, as a sequence. This gives the pack access to any libraries, database schema, and query suites defined in the dependency. Optionally a version for the dependency is specified. 
+     - The names and version ranges of any CodeQL packs that this pack depends on, as a mapping. This gives the pack access to any libraries, database schema, and query suites defined in the dependency. For more information, see `SemVer ranges <https://docs.npmjs.com/cli/v6/using-npm/semver#ranges>`__ in the NPM documentation.
    * - ``suites``
      - ``octo-org-query-suites``
      - Optional
@@ -93,12 +97,12 @@ The following properties are supported in ``qlpack.yml`` files.
    * - ``authors``
      - ``[email protected]``
      - All packs
-     - Metadata that will be displayed on the packaging search page in the packages section of the organization that a CodeQL pack is published to.
+     - Metadata that will be displayed on the packaging search page in the packages section of the account that the CodeQL pack is published to.
    * - ``licenses``
      - ``(LGPL-2.1 AND MIT)``
      - All packs
-     - Metadata that will be displayed on the packaging search page in the packages section of the organization that a CodeQL pack is published to.
+     - Metadata that will be displayed on the packaging search page in the packages section of the account that the CodeQL pack is published to. For a list of allowed licenses, see `SPDX License List <https://spdx.org/licenses/>`__ in the SPDX Specification. 
    * - ``description``
      - ``Human-readable description of the software packaged in the image.``
      - All packs
-     - Metadata that will be displayed on the packaging search page in the packages section of the organization that a CodeQL pack is published to.
+     - Metadata that will be displayed on the packaging search page in the packages section of the account that the CodeQL pack is published to.

docs/codeql/codeql-cli/creating-and-working-with-codeql-packs.rst

@@ -33,7 +33,7 @@ You can create a CodeQL pack by running the following command from the checkout
 
 You must specify:
 
-- ``<scope>``: the name of the GitHub organization that you will publish to.
+- ``<scope>``: the name of the GitHub organization or user account that you will publish to.
 - ``<pack>``: the name for the pack that you are creating.
 
 The ``codeql pack init`` command creates the directory structure and configuration files for a CodeQL pack. By default, the command creates a query pack. If you want to create a library pack, you must edit the ``qlpack.yml`` file to explicitly declare the file as a library pack by including the ``library:true`` property.
@@ -49,7 +49,7 @@ For more information about the properties, see ":ref:`About CodeQL packs <about-
 
 Adding and installing dependencies to a CodeQL pack
 ---------------------------------------------------
-You can add dependencies on CodeQL packs using the command ``codeql pack add``. You can specify the scope, name, and version.
+You can add dependencies on CodeQL packs using the command ``codeql pack add``. You must specify the scope, name, and version range.
 
 ::
 

docs/codeql/codeql-cli/publishing-and-using-codeql-packs.rst

@@ -22,14 +22,14 @@ You can check and modify the configuration details of your CodeQL pack prior to
    name: <scope>/<pack>
    version: <x.x.x>
    description: <Description to publish with the package>
-   default-suite: # a query-suite file that has been inlined
-       - query:
-   default-suite-file: default-queries.qls # a pointer to a query-suite in this pack
+   default-suite: # optional, one or more queries in the pack to run by default
+       - query: <relative-path>/query-file>.ql
+   default-suite-file: default-queries.qls # optional, a pointer to a query-suite in this pack
    license: # optional, the license under which the pack is published
    dependencies: # map from CodeQL pack name to version range
 
 - ``name:`` must follow the <scope>/<pack> format, where <scope> is the GitHub organization that you will publish to and <pack> is the name for the pack.
-- Only one of ``default-suite`` or ``default-suite-file`` is allowed. Both options define a default query suite to be run, the first by specifying queries directly in the `qlpack.yml` file and the second by specifying a query suite in the pack.
+- A maximum of one of ``default-suite`` or ``default-suite-file`` is allowed. These are two different ways to define a default query suite to be run, the first by specifying queries directly in the `qlpack.yml` file and the second by specifying a query suite in the pack.
 
 Running ``codeql pack publish``
 -------------------------------
@@ -55,7 +55,7 @@ To run a pack that someone else has created, you must first download it by runni
 - ``<pack>``: the name for the pack that you are creating.
 - ``@x.x.x``: an optional version number. If omitted, the latest version will be downloaded.
 
-This command accepts arguments for multiple packs, as well as query suites.
+This command accepts arguments for multiple packs.
 
 Using a CodeQL pack to analyze a CodeQL database
 ------------------------------------------------