further imrpovements

Author: jf205

docs/codeql/codeql-cli/analyzing-databases-with-the-codeql-cli.rst

@@ -66,7 +66,7 @@ You can also specify:
 - ``--sarif-add-query-help``: (supported in version 2.7.1 onwards) adds any custom query help written 
    in markdown to SARIF files (v2.1.0 or later) generated by the analysis. Query help stored in ``.qhelp`` files must be 
    converted to ``.md`` before running the analysis. For further information, 
-   see ":doc:`Including query help for custom CodeQL queries in SARIF files  <testing-query-help-files>`."
+   see ":ref:`Including query help for custom CodeQL queries in SARIF files  <including-query-help-for-custom-codeql-queries-in-sarif-files>`."
 
 - .. include:: ../reusables/threads-query-execution.rst
 
@@ -211,15 +211,21 @@ supported by CodeQL.
 Including query help for custom CodeQL queries in SARIF files 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Code scanning does not process ``.qhelp`` files for custom CodeQL queries, so to show 
-query help for custom queries in the code scanning UI you must include markdown-rendered query help 
-in SARIF files generated during an analysis.
+If you use the CodeQL CLI to to run code scanning analyses on third party CI/CD systems,
+you can include the query help for your custom queries in SARIF files generated during an analysis.
+After uploading the SARIF file to GitHub, the query help is shown in the code scanning UI for any 
+alerts generated by the custom queries. 
 
-For CodeQL CLI 2.7.1 onwards, you can include markdown-rendered query help in SARIF files 
+From CodeQL CLI 2.7.1 onwards, you can include markdown-rendered query help in SARIF files 
 by providing the ``--sarif-add-query-help`` option when running
-``codeql database analyze``. Query help written in ``.qhelp`` files cannot be include in SARIF files, 
-so must be converted to markdown before running the analysis. For more information, see 
-":ref:`Testing query help files <testing-query-help-files>`."
+``codeql database analyze``. 
+
+You can write query help for custom queries directly in markdown file and save it alongside the
+corresponding query. Alternatively, for consistency with the standard CodeQL queries, 
+you can write query help in the ``.qhelp`` format and convert it to markdown before 
+running the analysis. Query help written in ``.qhelp`` files can't be included in SARIF files, 
+and they can't be processed by code scanning. For more information, see 
+":doc:`Testing query help files <testing-query-help-files>`."
 
 Results
 -------

docs/codeql/codeql-cli/testing-query-help-files.rst

@@ -15,7 +15,7 @@ in the CodeQL repository.
 The CodeQL CLI includes a command to test query help and render the content as 
 markdown, so that you can easily preview the content in your IDE. Use the command to validate 
 query help files before uploading them to the CodeQL repository or sharing them with other users. 
-For CodeQL CLI 2.7.1 onwards, you can also include the markdown-rendered query help in SARIF files 
+From CodeQL CLI 2.7.1 onwards, you can also include the markdown-rendered query help in SARIF files 
 generated during CodeQL analyses so that the query help can be displayed in the code scanning UI. 
 For more information, see 
 ":ref:`Analyzing databases with the CodeQL CLI <including-query-help-for-custom-codeql-queries-in-sarif-files>`."