docs: update titles and intros (writing codeql queries)

Author: james

docs/language/learn-ql/intro-to-data-flow.rst

@@ -1,10 +1,11 @@
-Introduction to data flow analysis with CodeQL
-##############################################
+About data flow analysis
+########################
+
+Data flow analysis is used to compute the possible values that a variable can hold at various points in a program, determining how those values propagate through the program and where they are used. 
 
 Overview
 ********
 
-Data flow analysis computes the possible values that a variable can hold at various points in a program, determining how those values propagate through the program and where they are used. 
 Many CodeQL security queries implement data flow analysis, which can highlight the fate of potentially malicious or insecure data that can cause vulnerabilities in your code base.
 These queries help you understand if data is used in an insecure way, whether dangerous arguments are passed to functions, or whether sensitive data can leak.
 As well as highlighting potential security issues, you can also use data flow analysis to understand other aspects of how a program behaves, by finding, for example, uses of uninitialized variables and resource leaks.

docs/language/learn-ql/locations.rst

@@ -3,6 +3,9 @@ Locations and strings for QL entities
 
 .. Not sure how much of this topic needs to change, and what the title should be
 
+CodeQL includes mechanisms for extracting the location of elements in a codebase. Use these mechanisms when writing custom CodeQL queries and libraries to help display information to users.
+
+
 Providing locations
 -------------------
 

docs/language/learn-ql/writing-queries/debugging-queries.rst

@@ -1,5 +1,10 @@
-Query writing: common performance issues
-========================================
+Troubleshooting query performance
+=================================
+
+Improve the performance of your CodeQL queries by following a few simple guidelines.
+
+About query performance
+-----------------------
 
 This topic offers some simple tips on how to avoid common problems that can affect the performance of your queries.
 Before reading the tips below, it is worth reiterating a few important points about CodeQL and the QL language:
@@ -19,9 +24,7 @@ Eliminate cartesian products
 The performance of a predicate can often be judged by considering roughly how many results it has. 
 One way of creating badly performing predicates is by using two variables without relating them in any way, or only relating them using a negation.
 This leads to computing the `Cartesian product <https://en.wikipedia.org/wiki/Cartesian_product>`__ between the sets of possible values for each variable, potentially generating a huge table of results.
-
 This can occur if you don't specify restrictions on your variables. 
-
 For instance, consider the following predicate that checks whether a Java method ``m`` may access a field ``f``::
 
    predicate mayAccess(Method m, Field f) {

docs/language/learn-ql/writing-queries/introduction-to-queries.rst

@@ -1,14 +1,17 @@
-Introduction to query files
-###########################
+About CodeQL queries
+####################
+
+CodeQL queries are used to analyze code for issues related to security, correctness, maintainability, and readability. 
 
 Overview
 ********
 
-Queries are programs written with CodeQL. They are designed to highlight issues related to the security, correctness, maintainability, and readability of a code base. You can also write custom queries to find specific issues relevant to your own project. Three important types of query are:
+CodeQL includes queries to find the relevant and interesting problems for a each supported language. You can also write custom queries to find specific issues relevant to your own project.
+
+The important types of query are:
 
 - **Alert queries**: queries that highlight issues in specific locations in your code.
 - **Path queries**: queries that describe the flow of information between a source and a sink in your code.
-- **Metric queries**: queries that compute statistics for your code.
 
 You can add custom queries to `custom query packs <https://lgtm.com/help/lgtm/about-queries#what-are-query-packs>`__ to analyze your projects in `LGTM <https://lgtm.com>`__, use them to analyze a database with the `CodeQL CLI <https://help.semmle.com/codeql/codeql-cli.html>`__, or you can contribute to the standard CodeQL queries in our `open source repository on GitHub <https://github.com/semmle/ql>`__.
 
@@ -78,7 +81,7 @@ When writing your own alert queries, you would typically import the standard lib
 
 - C/C++: ``cpp``
 - C#: ``csharp``
-- COBOL: ``cobol``
+- Go: ``go``
 - Java: ``java``
 - JavaScript/TypeScript: ``javascript``
 - Python: ``python``
@@ -87,11 +90,10 @@ There are also libraries containing commonly used predicates, types, and other m
 
 You can explore the contents of all the standard libraries in the `CodeQL library reference documentation <https://help.semmle.com/QL/ql-libraries.html>`__ or in the `GitHub repository <https://github.com/semmle/ql>`__.
 
-
 Optional CodeQL classes and predicates
 --------------------------------------
 
-You can customize your analysis by defining your own predicates and classes in the query. See `Defining a predicate <https://help.semmle.com/QL/ql-handbook/predicates.html#defining-a-predicate>`__ and `Defining a class <https://help.semmle.com/QL/ql-handbook/types.html#defining-a-class>`__ for further details. 
+You can customize your analysis by defining your own predicates and classes in the query. For further information, see `Defining a predicate <https://help.semmle.com/QL/ql-handbook/predicates.html#defining-a-predicate>`__ and `Defining a class <https://help.semmle.com/QL/ql-handbook/types.html#defining-a-class>`__. 
 
 From clause
 ===========

docs/language/learn-ql/writing-queries/path-queries.rst

@@ -1,5 +1,7 @@
-Constructing path queries
-#########################
+Creating path queries
+#####################
+
+You can create path queries to visualize the flow of information through a codebase.
 
 Overview
 ========

docs/language/learn-ql/writing-queries/query-help.rst

@@ -1,5 +1,7 @@
-Query help reference
-********************
+Query help files
+****************
+
+Query help files tell users the purpose of a query, and recommend how to solve the potential problem the query finds.
 
 This topic provides detailed information on the structure of query help files. 
 For more information about how to write useful query help in a style that is consistent with the standard CodeQL queries, see the `Query help style guide <https://github.com/Semmle/ql/blob/master/docs/query-help-style-guide.md>`__ on GitHub.

docs/language/learn-ql/writing-queries/query-metadata.rst

@@ -1,5 +1,10 @@
-Query metadata
-==============
+Metadata for CodeQL queries
+===========================
+
+Metadata is used to tell users important information about CodeQL queries. You must include the correct query metadata in a query to be able to view query results in source code.
+
+About query metadata
+--------------------
 
 Any query that is run as part of an analysis includes a number of properties, known as query metadata. Metadata is included at the top of each query file as the content of a `QLDoc <https://help.semmle.com/QL/ql-spec/qldoc.html>`__ comment. 
 For alerts and path queries, this metadata tells LGTM and the CodeQL `extension for VS Code <https://help.semmle.com/codeql/codeql-for-vscode.html>`__ how to handle the query and display its results correctly. 

docs/language/learn-ql/writing-queries/select-statement.rst

@@ -1,5 +1,10 @@
-Defining 'select' statements
-============================
+Defining the results of a query
+===============================
+
+You can control how analysis results are displayed in source code by modifying a query's ``select`` statement.
+
+About query results
+-------------------
 
 The information contained in the results of a query is controlled by the ``select`` statement. Part of the process of developing a useful query is to make the results clear and easy for other users to understand.
 When you write your own queries in the query console or in the CodeQL `extension for VS Code <https://help.semmle.com/codeql/codeql-for-vscode.html>`__ there are no constraints on what can be selected.