Edits based on Jesse's feedback

Author: Lauren

v2.1/explain.md

@@ -58,14 +58,14 @@ The user requires the appropriate [privileges](privileges.html) for the statemen
 
 ## Parameters
 
-| Parameter | Description |
-|-----------|-------------|
+Parameter | Description
+-----------|-----------
 `EXPRS` | Include the SQL expressions that are involved in each processing stage.
 `QUALIFY` | Include table names when referencing columns, which might be important to verify the behavior of joins across tables with the same column names.<br/><br/>To list qualified names, `QUALIFY` requires you to include the `EXPRS` option.
 `METADATA` | Include the columns each level uses in the **Columns** column, as well as **Ordering** detail.
 `VERBOSE`  | Imply the `EXPRS`, `METADATA`, and `QUALIFY` options.
 `TYPES` | Include the intermediate [data types](data-types.html) CockroachDB chooses to evaluate intermediate SQL expressions. <br/><br/>`TYPES` also implies `METADATA` and `EXPRS` options.
-`OPT` | Display a query plan tree if the query will be run with the [cost-based Optimizer](sql-optimizer.html). If it returns `pq: unsupported statement: *tree.Insert`, the query will not be run with the cost-based Optimizer and will be run with the legacy heuristic planner.
+`OPT` | Display a query plan tree if the query will be run with the [cost-based optimizer](sql-optimizer.html). If it returns `pq: unsupported statement: *tree.Insert`, the query will not be run with the cost-based optimizer and will be run with the heuristic planner.
 `explainable_stmt` | The [statement](#explainable-statements) you want details about.
 
 {{site.data.alerts.callout_danger}}<code>EXPLAIN</code> also includes other modes besides query plans that are useful only to CockroachDB developers, which are not documented here.{{site.data.alerts.end}}
@@ -74,13 +74,13 @@ The user requires the appropriate [privileges](privileges.html) for the statemen
 
 Successful `EXPLAIN` statements return tables with the following columns:
 
-| Column | Description |
-|-----------|-------------|
-| **Tree** | A tree representation showing the hierarchy of the query plan.
-| **Field** | The name of a parameter relevant to the query plan node immediately above. |
-| **Description** | Additional information for the parameter in  **Field**. |
-| **Columns** | The columns provided to the processes at lower levels of the hierarchy. <br/><br>This column displays only if the `METADATA` option is specified or implied. |
-| **Ordering** | The order in which results are presented to the processes at each level of the hierarchy, as well as other properties of the result set at each level. <br/><br>This column displays only if the `METADATA` option is specified or implied. |
+ Column | Description
+-----------|-------------
+**Tree** | A tree representation showing the hierarchy of the query plan.
+**Field** | The name of a parameter relevant to the query plan node immediately above.
+**Description** | Additional information for the parameter in  **Field**.
+**Columns** | The columns provided to the processes at lower levels of the hierarchy. <br/><br>This column displays only if the `METADATA` option is specified or implied.
+**Ordering** | The order in which results are presented to the processes at each level of the hierarchy, as well as other properties of the result set at each level. <br/><br>This column displays only if the `METADATA` option is specified or implied.
 
 ## Examples
 
@@ -318,7 +318,7 @@ The `TYPES` mode includes the types of the values used in the query plan, and im
 
 ### `OPT` option
 
-<span class="version-tag">New in v2.1:</span> The `OPT` option displays a query plan tree if the query will be run with the [cost-based Optimizer](sql-optimizer.html). If it returns `pq: unsupported statement: *tree.Insert`, the query will not be run with the cost-based Optimizer and will be run with the legacy heuristic planner.
+<span class="version-tag">New in v2.1:</span> The `OPT` option displays a query plan tree if the query will be run with the [cost-based optimizer](sql-optimizer.html). If it returns `pq: unsupported statement: *tree.Insert`, the query will not be run with the cost-based optimizer and will be run with the heuristic planner.
 
 For example:
 
@@ -351,7 +351,7 @@ For example:
 (15 rows)
 ~~~
 
-The query above will be run with the cost-based Optimizer and `EXPLAIN (OPT)` returns the query plan tree.
+The query above will be run with the cost-based optimizer and `EXPLAIN (OPT)` returns the query plan tree.
 
 
 {% include copy-clipboard.html %}
@@ -363,7 +363,7 @@ The query above will be run with the cost-based Optimizer and `EXPLAIN (OPT)` re
 pq: unsupported statement: *tree.Insert
 ~~~
 
-The query above will not be run with the cost-based Optimizer.
+The query above will not be run with the cost-based optimizer.
 
 ### Find the indexes and key ranges a query uses
 

v2.1/sql-optimizer.md

@@ -1,26 +1,26 @@
 ---
 title: SQL Optimizer
-summary: Learn about the SQL Optimizer
-toc: false
+summary: Learn about the SQL optimizer
+toc: true
 ---
 
-<span class="version-tag">New in v2.1:</span> The cost-based Optimizer seeks the lowest cost for a query, usually related to time.
+<span class="version-tag">New in v2.1:</span> The cost-based optimizer seeks the lowest cost for a query, usually related to time.
 
 In versions prior to v2.1, a heuristic planner was used to generate query execution plans.
-In version 2.1, CockroachDB's new **cost-based Optimizer will be enabled by default**, and the legacy heuristic planner will only be used in the following cases:
+In version 2.1, CockroachDB's new **cost-based optimizer will be enabled by default**, and the heuristic planner will only be used in the following cases:
 
-- If your query uses functionality that is not supported by the cost-based Optimizer
-- If you explicitly [turn off the cost-based Optimizer](#how-to-turn-the-optimizer-off)
+- If your query uses functionality that is not supported by the cost-based optimizer
+- If you explicitly [turn off the cost-based optimizer](#how-to-turn-the-optimizer-off)
 
 {% include {{ page.version.version }}/misc/beta-warning.md %}
 
 <div id="toc"></div>
 
 ## View query plan
 
-To see whether a given query will be run with the cost-based Optimizer, run the query with [`EXPLAIN (OPT)`](explain.html#opt-option). If `EXPLAIN (OPT)` returns a query plan tree, that query will be run with the cost-based Optimizer. If it returns `pq: unsupported statement: *tree.Insert`, the query will not be run with the cost-based Optimizer.
+To see whether a query will be run with the cost-based optimizer, run the query with [`EXPLAIN (OPT)`](explain.html#opt-option). If `EXPLAIN (OPT)` returns a query plan tree, the query will use the cost-based optimizer. If it returns `pq: unsupported statement: *tree.Insert`, the query will use the heuristic planner.
 
-For example:
+For example, the following query returns the query plan tree, which means that it will be run with the cost-based optimizer:
 
 {% include copy-clipboard.html %}
 ~~~ sql
@@ -51,8 +51,7 @@ For example:
 (15 rows)
 ~~~
 
-The query above will be run with the cost-based Optimizer and `EXPLAIN (OPT)` returns the query plan tree.
-
+In contrast, this query returns `pq: unsupported statement: *tree.Insert`, which means that it will use the legacy heuristic planner instead of the cost-based optimizer:
 
 {% include copy-clipboard.html %}
 ~~~ sql
@@ -63,34 +62,32 @@ The query above will be run with the cost-based Optimizer and `EXPLAIN (OPT)` re
 pq: unsupported statement: *tree.Insert
 ~~~
 
-The query above will not be run with the cost-based Optimizer.
-
-## How to turn the Optimizer off
+## How to turn the optimizer off
 
-With the Optimizer turned on, the performance of some workloads may change. If your workload performs worse than expected (e.g., lower throughput or higher latency), you can turn off the cost-based Optimizer and use the heuristic Optimizer.
+With the optimizer turned on, the performance of some workloads may change. If your workload performs worse than expected (e.g., lower throughput or higher latency), you can turn off the cost-based optimizer and use the heuristic planner.
 
-To turn the cost-based Optimizer off by session:
+To turn the cost-based optimizer off for the current session:
 
 {% include copy-clipboard.html %}
 ~~~ sql
 > SET experimental_opt = 'off';
 ~~~
 
-To change the cost-based Optimizer's default cluster setting:
+To turn the cost-based optimizer off for all sessions:
 
 {% include copy-clipboard.html %}
 ~~~ sql
 > SET CLUSTER SETTING sql.defaults.optimizer = 'off';
 ~~~
 
 {{site.data.alerts.callout_info}}
-Changing the cluster setting does not immediately turn the Optimizer off; instead, it changes the default session setting to `off`. To see the change, restart your session.
+Changing the cluster setting does not immediately turn the optimizer off; instead, it changes the default session setting to `off`. To see the change, restart your session.
 {{site.data.alerts.end}}
 
 ## Known limitations
 
-- The optimizer will not support automated use of statistics during this time period.
-- Some features present in v2.0 are not supported by the Optimizer; however, the Optimizer will fall back to the v2.0 code path for this functionality. If performance in the new alpha is worse than v2.0, you can [turn the Optimizer off](#how-to-turn-the-optimizer-off) to manually force it to fallback to the heuristic planner.
+- The cost-based optimizer will not support automated use of statistics during this time period.
+- Some features present in v2.0 are not supported by the cost-based optimizer; however, the optimizer will fall back to the v2.0 code path for this functionality. If performance in the new alpha is worse than v2.0, you can [turn the optimizer off](#how-to-turn-the-optimizer-off) to manually force it to fallback to the heuristic planner.
 - Some correlated subqueries are not supported yet.
 
 ## See also