address review comments

Author: jf205

docs/codeql/codeql-cli/creating-codeql-databases.rst

@@ -5,11 +5,17 @@ Creating CodeQL databases
 
 Before you analyze your code using CodeQL, you need to create a CodeQL
 database containing all the data required to run queries on your code.
+You can create CodeQL databases yourself using the CodeQL CLI,
+or download them from GitHub.com.
 
 CodeQL analysis relies on extracting relational data from your code, and
 using it to build a :ref:`CodeQL database <codeql-database>`. CodeQL
 databases contain all of the important information about a codebase, which can
-be analyzed by executing CodeQL queries against it.
+be analyzed by executing CodeQL queries against it. GitHub creates and 
+stores CodeQL databases for a large number of open-source projects. For more information,
+see ":ref:`Downloading CodeQL databases from GitHub.com <downloading-codeql-databases-from-github-com>`."
+
+You can also create CodeQL databases yourself using the CodeQL CLI. 
 Before you generate a CodeQL database, you need to:
 
 - Install and set up the CodeQL CLI. For more information, see
@@ -379,6 +385,8 @@ The following example shows how you could use indirect build tracing in an Azure
        # `codeql database analyze`
        # then `codeql github upload-results` ...
 
+.. _downloading-databases-from-github-com:
+
 Downloading databases from GitHub.com
 -------------------------------------
 

docs/codeql/codeql-for-visual-studio-code/analyzing-your-projects.rst

@@ -14,7 +14,7 @@ To analyze a project, you need to add a :ref:`CodeQL database <codeql-database>`
 
 #. Open the CodeQL Databases view in the sidebar.
 
-#. Hover over the **Databases** title bar and click the appropriate icon to add your database. You can add a database from a local ZIP archive or folder, from a public URL, or from a project slug on GitHub.com.
+#. Hover over the **Databases** title bar and click the appropriate icon to add your database. You can add a database from a local ZIP archive or folder, from a public URL, or from a project's URL on GitHub.com.
 
    .. image:: ../images/codeql-for-visual-studio-code/choose-database.png
       :width: 350

docs/codeql/reusables/download-github-database.rst

@@ -1,5 +1,14 @@
 GitHub stores CodeQL databases for over 200,000 repos on GitHub.com, which you can download using the REST API. The list of repos is constantly growing and evolving to make sure that it includes the most interesting codebases for security research.
 
-To download a database from GitHub.com using the `GitHub CLI <https://cli.github.com/manual/gh_api>`__, use the following command:: 
+You can check if a repo has any CodeQL databases available to download using the `/repos/<owner>/<repo>/code-scanning/codeql/databases` endpoint.
+For example, to check for CodeQL databases using the `GitHub CLI <https://cli.github.com/manual/gh_api>`__ you would run::
+
+   gh api /repos/<owner>/<repo>/code-scanning/codeql/databases/
+
+This command will return information about the CodeQL databases that are available for a repository, including the language the database represents, and when the database was last updated. If no CodeQL databases are available, the response will be empty.
+
+When you have confirmed that a CodeQL database exists for the language you are interested in, you can download it using the following command:: 
 
    gh api /repos/<owner>/<repo>/code-scanning/codeql/databases/<language> -H 'Accept: application/zip' > path/to/local/database.zip
+
+TODO: add link to the REST API docs.