Editing pass. (#608)

* Editing pass at mostly final docs.

---------

Co-authored-by: Trey Spiller <treyspiller@gmail.com>

Author: technically-tracy

docs/best_practices/recommended_workflow.md

@@ -7,9 +7,9 @@ There are many tools and frameworks in the data ecosystem. This page tries to ma
 ## dbt
 [dbt](https://www.getdbt.com/) is a tool for data transformations. It is a pioneer in this space and has shown how valuable transformation frameworks can be. Although dbt is a fanstastic tool, it has trouble scaling with data and organizational size.
 
-SQLMesh aims to be dbt format compatible. Importing existing dbt projects with minor changes is in development.
+SQLMesh aims to be dbt format-compatible. Importing existing dbt projects with minor changes is in development.
 
-### Feature Comparisons
+### Feature comparisons
 | Feature                           | dbt | SQLMesh
 | -------                           | --- | -------
 | `SQL models`                      | ✅ | ✅
@@ -42,8 +42,8 @@ SQLMesh aims to be dbt format compatible. Importing existing dbt projects with m
 | `Comprehensive Python API`        | ❌ | ✅
 
 
-### Incremental Models
-Implementing an incremental model is difficult and error-prone in dbt because it does not keep track of state. Since there is no state in dbt, the user must write subqueries to find missing date boundaries.
+### Incremental models
+Implementing an incremental model is difficult and error-prone in dbt, because dbt does not keep track of state. Since there is no state in dbt, the user must write subqueries to find missing date boundaries.
 
 #### Complexity
 ```sql
@@ -62,9 +62,9 @@ WHERE e.ds >= (SELECT MAX(ds) FROM {{ this }})
 {% endif %}
 ```
 
-Having to manually specify macros to find date boundaries is repetitive and error-prone. As incremental models become more complex, the cognitive burden of having two run times, "first time full refresh" vs "subsequent incremental", increases.
+Having to manually specify macros to find date boundaries is repetitive and error-prone. As incremental models become more complex, the cognitive burden of having two run times, "first time full refresh" vs. "subsequent incremental", increases.
 
-SQLMesh keeps track of which date ranges exist so the query can be simplified as follows.
+SQLMesh keeps track of which date ranges exist so that the query can be simplified as follows:
 
 ```sql
 -- sqlmesh incremental
@@ -77,9 +77,9 @@ WHERE d.ds BETWEEN @start_ds AND @end_ds
 ```
 
 #### Data leakage
-dbt does not enforce that the data inserted into the incremental table should be there. This can lead to problems or consistency issues such as late arriving data overriding past partitions. SQLMesh wraps all queries under the hood in a subquery with a time filter to enforce that the data inserted for a particular batch is as expected.
+dbt does not enforce that the data inserted into the incremental table should be there. This can lead to problems or consistency issues, such as late-arriving data overriding past partitions. SQLMesh wraps all queries under the hood in a subquery with a time filter to enforce that the data inserted for a particular batch is as expected.
 
-dbt also only supports the 'insert/overwrite' incremental load pattern for systems that natively support it. SQLMesh enables 'insert/overwrite' on any system because it is the most robust way to do incremental pipelines. 'Append' pipelines risk data accuracy in the variety of scenarios where your pipelines may run more than once for a given date.
+dbt also only supports the 'insert/overwrite' incremental load pattern for systems that natively support it. SQLMesh enables 'insert/overwrite' on any system, because it is the most robust way to do incremental pipelines. 'Append' pipelines risk data accuracy in the variety of scenarios where your pipelines may run more than once for a given date.
 
 
 ```sql
@@ -103,15 +103,15 @@ WHERE ds BETWEEN @start_ds AND @end_ds
 ```
 
 #### Data gaps
-The main pattern used in incremental models checks for MAX(ds). This pattern does not catch missing data from the past or data gaps.
+The main pattern used in incremental models checks for MAX(ds). This pattern does not catch missing data from the past, or data gaps.
 
 ```
 Expected dates: 2022-01-01, 2022-01-02, 2022-01-03
 Missing past data: ?, 2022-01-02, 2022-01-03
 Data gap: 2022-01-01, ?, 2022-01-03
 ```
 
-SQLMesh stores each date interval a model has been run with so that it knows exactly what dates are missing.
+SQLMesh stores each date interval a model has been run with, so it knows exactly what dates are missing.
 
 #### Performance
 The subqueries that look for MAX(date) could have a performance impact on the query. SQLMesh is able to avoid these extra subqueries.

docs/comparisons.md

@@ -4,7 +4,7 @@ SQLMesh executes Python code through [macros](../macros.md) and [Python models](
 
 ## Serialization format
 
-Rather than using Python's `pickle` format, SQLMesh has it's own serialization format. This is because `pickle` is not compatible across Python versions, and would for example prevent you from developing on Python 3.7 and then running Python 3.8 in production. 
+Rather than using Python's `pickle` format, SQLMesh has it's own serialization format. This is because `pickle` is not compatible across Python versions, and would, for example, prevent you from developing on Python 3.7 and then running Python 3.8 in production. 
 
 Instead, SQLMesh stores the string representation of your Python implementation and then re-evaluates it. Given a custom Python function or macro, SQLMesh reads the Abstract Syntax Tree (AST) of the function and converts that into a string representation, along with all dependencies and global variables. For more information, refer to [snapshot fingerprinting](../architecture/snapshots.md#fingerprinting).
 

docs/concepts/architecture/serialization.md

@@ -1,5 +1,5 @@
 # Snapshots
-A snapshot is a record of a model at a given time. Along with a copy of the model, a snapshot contains everything needed to evaluate the model and render its query. This allows SQLMesh to have a consistent view of your project's history and its data as the project and its models evolve and change. Since model queries can have macros, each snapshot stores a copy of all macro definitions and global variables at the time the snapshot is taken. Additionally, snapshots store the intervals of time they have data for.
+A snapshot is a record of a model at a given time. Along with a copy of the model, a snapshot contains everything needed to evaluate the model and render its query. This allows SQLMesh to have a consistent view of your project's history and its data as the project and its models evolve and change. Since model queries can have macros, each snapshot stores a copy of all macro definitions and global variables at the time the snapshot is taken. Additionally, snapshots store the intervals of time for which they have data.
 
 ## Fingerprinting
 Snapshots have unique fingerprints that are derived from their models. SQLMesh uses these fingerprints

docs/concepts/architecture/snapshots.md

@@ -42,7 +42,7 @@ AUDIT (
 SELECT * FROM @this_model
 WHERE @column >= @threshold;
 ```
-In the example above we utilized [Macros](macros.md) to parameterize the audit implementation. `@this_model` is a special macro which refers to a model that is being audited. For incremental models, this macro also ensures that only relevant data intervals are affected. `@column` and `@threshold` are generic parameters, values for which are set in the model definition.
+In the example above we utilized [macros](macros.md) to parameterize the audit implementation. `@this_model` is a special macro which refers to a model that is being audited. For incremental models, this macro also ensures that only relevant data intervals are affected. `@column` and `@threshold` are generic parameters, values for which are set in the model definition.
 
 The generic audit can now be applied to a model by being referenced in its definition:
 ```sql linenums="1"
@@ -56,7 +56,7 @@ MODEL (
 ```
 Notice how `column` and `threshold` parameters have been set at this point. These values will later be propagated into the audit query and returned by the `@column` and `@threshold` macros accordingly.
 
-Please also note that the same audit can be applied more than once to the same model with different sets of parameters.
+Note that the same audit can be applied more than once to the same model with different sets of parameters.
 
 ## Built-in audits
 SQLMesh comes with a suite of built-in generic audits which covers a broad set of common use cases.
@@ -75,7 +75,7 @@ MODEL (
 ```
 
 ### unique_values
-Makes sure that provided columns only contain unique values.
+Ensures that provided columns only contain unique values.
 
 Example:
 ```sql linenums="1"
@@ -101,7 +101,7 @@ MODEL (
 ```
 
 ### number_of_rows
-Ensures that the number of rows in the model's table exceeds the configured threshold. For incremental models this check only applies to a data interval that is being evaluated, and not to the entire table.
+Ensures that the number of rows in the model's table exceeds the configured threshold. For incremental models, this check only applies to a data interval that is being evaluated, not to the entire table.
 
 Example:
 ```sql linenums="1"

docs/concepts/audits.md

@@ -1,12 +1,12 @@
 ## Environments
 Environments are isolated namespaces that allow you to test and preview your changes.
 
-SQLMesh differentiates between production and development environments. Currently only the environment with the name `prod` is treated by SQLMesh as the production one. Environments with other names are considered to be development ones.
+SQLMesh differentiates between production and development environments. Currently, only the environment with the name `prod` is treated by SQLMesh as the production one. Environments with other names are considered to be development ones.
 
 [Models](models/overview.md) in development environments get a special suffix appended to the schema portion of their names. For example, to access data for a model with name `db.model_a` in the target environment `my_dev`, the `db__my_dev.model_a` table name should be used in a query. Models in the production environment are referred to by their original names.
 
 ## Why use environments
-Data pipelines and their dependencies tend to grow in complexity over time and so assessing the impact of local changes can become quite challenging. Pipeline owners may not be aware of all downstream consumers of their pipelines, or may drastically underestimate the impact a change would have. That's why it is so important to be able to iterate and test model changes using production dependencies and data, while simultaneously avoiding any impact to existing datasets and/or pipelines that are currently used in production. Recreating the entire data warehouse with given changes would be an ideal solution to fully understand their impact, but this process is usually excessively expensive and time consuming.
+Data pipelines and their dependencies tend to grow in complexity over time, and so assessing the impact of local changes can become quite challenging. Pipeline owners may not be aware of all downstream consumers of their pipelines, or may drastically underestimate the impact a change would have. That's why it is so important to be able to iterate and test model changes using production dependencies and data, while simultaneously avoiding any impact to existing datasets or pipelines that are currently used in production. Recreating the entire data warehouse with given changes would be an ideal solution to fully understand their impact, but this process is usually excessively expensive and time consuming.
 
 SQLMesh environments allow you to easily spin up shallow 'clones' of the data warehouse quickly and efficiently. SQLMesh understands which models have changed compared to the target environment, and only computes data gaps that have been directly caused by the changes. Any changes or backfills within the target environment **do not impact** other environments. At the same time, any computation that was done in this environment **can be safely reused** in other environments.
 
@@ -16,17 +16,17 @@ When running the [plan](plans.md) command, the environment name can be supplied
 By default, the [`sqlmesh plan`](plans.md) command targets the production (`prod`) environment.
 
 ### Example
-A custom name can be provided as an argument to create/update a development environment. For example, to target an environment with name `my_dev`, run:
+A custom name can be provided as an argument to create or update a development environment. For example, to target an environment with name `my_dev`, run:
 
 ```bash
 sqlmesh plan my_dev
 ```
 A new environment is created automatically the first time a plan is applied to it.
 
-## How do environments work
+## How environments work
 Whenever a model definition changes, a new model snapshot is created with a unique [fingerprint](architecture/snapshots.md#fingerprints). This fingerprint allows SQLMesh to detect if a given model variant exists in other environments or if it's a brand new variant. Because models may depend on other models, the fingerprint of a target model variant also includes fingerprints of its upstream dependencies. If a fingerprint already exists in SQLMesh, it is safe to reuse the existing physical table associated with that model variant, since we're confident that the logic that populates that table is exactly the same. This makes an environment a collection of references to model [snapshots](architecture/snapshots.md).
 
-Please refer to the [Plans](plans.md#plan-application) page for additional details.
+Refer to [plans](plans.md#plan-application) for additional details.
 
 ## Date range
 A development environment includes a start date and end date. When creating a development environment, the intent is usually to test changes on a subset of data. The size of such a subset is determined by a time range defined through the start and end date of the environment. Both start and end date are provided during the [plan](plans.md) creation.

docs/concepts/environments.md

@@ -42,14 +42,20 @@ Combining data from various sources (such as from a data warehouse) into one uni
 ## Lineage
 The lineage of your data is a visualization of the life cycle of your data as it flows from data sources downstream to consumption.
 
+## Slowly Changing Dimension (SCD)
+A dimension (in a data warehouse, typically a dataset) containing relatively static data that can change slowly but unpredictably, rather than on a regular schedule. Some examples of typical slowly changing dimensions are places and products.
+
 ## Table
 A table is the visual representation of data stored in rows and columns.
 
+## User-Defined Function (UDF)
+Functions that a user of a database server provides to extend its functionality, in contrast to built-in functions that are already provided. UDFs are typically written to satisfy the particular requirements of the user.
+
 ## View
 A view is the result of a SQL query on a database.
 
 ## Virtual Data Marts
-Term used to describe's SQLMesh's ability to share tables across environments to ensure tables are only built once while maintaining data integrity and environment isolation. See [Plan Application](plans.md#plan-application) for more information. 
+Term used to describes SQLMesh's ability to share tables across environments to ensure tables are only built once while maintaining data integrity and environment isolation. See [plan application](plans.md#plan-application) for more information. 
 
 ## Virtual Update
-Term used to describe a plan that can be applied without having to load any additional data or build any additional tables. See [Plan's Virtual Update](plans.md#virtual-update) for more information.
+Term used to describe a plan that can be applied without having to load any additional data or build any additional tables. See [Virtual Update](plans.md#virtual-update) for more information.

docs/concepts/glossary.md

@@ -1,3 +1,3 @@
 # Hooks
 
-TODO
+TBD

docs/concepts/hooks.md

@@ -1,6 +1,6 @@
 # Macros
 
-Although SQL is not dynamic, data pipelines need some form of dynamicism to be useful. For example, you may want a SQL query that runs the same logic except for a filter on dates that should change with every invocation.
+Although SQL is not dynamic, data pipelines need some form of dynamicism in order to be useful. For example, you may want a SQL query that runs the same logic except for a filter on dates that should change with every invocation.
 
 ```sql linenums="1"
 SELECT *
@@ -71,7 +71,7 @@ Variables:
     * @latest_millis
 
 ## Jinja
-[Jinja](https://jinja.palletsprojects.com/en/3.1.x/) is a popular templating tool for creating dynamic SQL and **is supported** by SQLMesh, but there are some drawbacks which lead for us to create our own Macro system.
+[Jinja](https://jinja.palletsprojects.com/en/3.1.x/) is a popular templating tool for creating dynamic SQL and is supported by SQLMesh, but there are some drawbacks which lead for us to create our own macro system.
 
 * Jinja is not valid SQL and not parseable.
 ```sql linenums="1"
@@ -80,9 +80,9 @@ SE{{ 'lect' }} x {{ 'AS ' + var }}
 FROM {{ 'table CROSS JOIN z' }}
 ```
 
-* Jinja is verbose and difficult to debug
+* Jinja is verbose and difficult to debug.
 ```sql linenums="1"
-TODO example with multiple for loops with trailing or leading comma
+TBD example with multiple for loops with trailing or leading comma
 ```
 * No concepts of types. Easy to miss quotes.
 

docs/concepts/macros.md

@@ -84,7 +84,7 @@ WHERE
 ### Idempotency
 It is recommended to ensure that queries of models of this kind are [idempotent](../../glossary/#idempotency) to prevent unexpected results during data [restatement](../plans.md#restatement-plans). 
 
-Please note, however, that upstream models and tables can impact the extent to which the idempotency property can be guaranteed. For example, referencing an upstream model of kind [FULL](#full) in the model query automatically renders such a model as non-idempotent.
+ Note, however, that upstream models and tables can impact the extent to which the idempotency property can be guaranteed. For example, referencing an upstream model of kind [FULL](#full) in the model query automatically renders such a model as non-idempotent.
 
 ### Materialization strategy
 Depending on the target engine, models of the `INCREMENTAL_BY_TIME_RANGE` kind are materialized using the following strategies:
@@ -107,7 +107,7 @@ This kind signifies that a model should be computed incrementally based on a uni
 * There should be at most one record associated with each unique key.
 * It is appropriate to upsert records, meaning existing records can be overridden by new arrivals when their keys match.
 
-[Slowly Changing Dimensions](https://en.wikipedia.org/wiki/Slowly_changing_dimension) (SCD) is one example that fits this description well.
+A [Slowly Changing Dimension](../glossary.md#slowly-changing-dimension-scd) (SCD) is one example that fits this description well.
 
 The name of the unique key column must be provided as part of the model definition, as in the following example:
 ```sql linenums="1"
@@ -198,7 +198,7 @@ Other model kinds cause the output of a model query to be materialized and store
 
 **Note:** With this kind, the model's query is evaluated every time the model is referenced in downstream queries. This may incur undesirable compute cost in cases where the model's query is compute-intensive, or when the model is referenced in many downstream queries.
 
-View is the default model kind if kind is not specified.
+View is the default model kind if the kind is not specified.
 
 Example:
 ```sql linenums="1"