Apply 10 suggestion(s) to 2 file(s)

doc/development/snowplow/review_guidelines.md

@@ -18,7 +18,7 @@ general best practices for code reviews, refer to our [code review guide](../cod
 
 ## Review process
 
-We recommend a Product Intelligence review when an MR involve changes in
+We recommend a Product Intelligence review when a merge request (MR) involves changes in
 events or touches Snowplow related files.
 
 ### Roles and process

doc/development/usage_ping/review_guidelines.md

@@ -18,16 +18,16 @@ general best practices for code reviews, refer to our [code review guide](../cod
 
 ## Review process
 
-We recommend a Product Intelligence review when an application update touches
-Usage Ping files.
+We recommend a Product Intelligence review when a merge request (MR) touches
+any of the following Usage Ping files:
 
-- Changes that touch `usage_data*` files.
-- Changes to the Metrics Dictionary including files in:
+- `usage_data*` files.
+- The Metrics Dictionary, including files in:
   - [`config/metrics`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/config/metrics).
   - [`ee/config/metrics`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/ee/config/metrics).
   - [`dictionary.md`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/development/usage_ping/dictionary.md).
   - [`schema.json`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/schema.json).
-- Changes to Product Intelligence tooling. For example,
+- Product Intelligence tooling. For example,
   [`Gitlab::UsageMetricDefinitionGenerator`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/generators/gitlab/usage_metric_definition_generator.rb)
 
 ### Roles and process
@@ -39,11 +39,11 @@ Usage Ping files.
   `~product intelligence` and `~product intelligence::review pending`.
 - Assign an
   [engineer](https://gitlab.com/groups/gitlab-org/growth/product-intelligence/engineers/-/group_members?with_inherited_permissions=exclude) from the Product Intelligence team for a review.
-- Set the correct attributes in YAML metrics:
+- Set the correct attributes in the metric's YAML definition:
   - `product_section`, `product_stage`, `product_group`, `product_category`
   - Provide a clear description of the metric.
 - Update the
-  [Metrics Dictionary](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/development/usage_ping/dictionary.md) if it is needed.
+  [Metrics Dictionary](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/development/usage_ping/dictionary.md) if needed.
 - Add a changelog [according to guidelines](../changelog.md).
 
 #### The Product Intelligence **reviewer** should
@@ -51,15 +51,15 @@ Usage Ping files.
 - Perform a first-pass review on the merge request and suggest improvements to the author.
 - Check the [metrics location](index.md#1-naming-and-placing-the-metrics) in
   the Usage Ping JSON payload.
-- Add `~database` label and ask for [database review](../database_review.md) for
+- Add the `~database` label and ask for a [database review](../database_review.md) for
   metrics that are based on Database.
 - For tracking using Redis HLL (HyperLogLog):
   - Check the Redis slot.
   - Check if a [feature flag is needed](index.md#recommendations).
-- Metrics YAML definitions:
-  - Check the metric `description`.
-  - Check the metrics `key_path`.
-  - Check the `product_section`, `product_stage`, `product_group`, `product_category`.
+- For a metric's YAML definition:
+  - Check the metric's `description`.
+  - Check the metric's `key_path`.
+  - Check the `product_section`, `product_stage`, `product_group`, and `product_category` fields.
     Read the [stages file](https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/stages.yml).
   - Check the file location. Consider the time frame, and if the file should be under `ee`.
   - Check the tiers.
@@ -67,7 +67,7 @@ Usage Ping files.
 
 ## Review workload distribution
 
-[Danger bot](../dangerbot.md) adds the list of Product Intelligence changed files
+[Danger bot](../dangerbot.md) adds the list of changed Product Intelligence files
 and pings the
 [`@gitlab-org/growth/product-intelligence/engineers`](https://gitlab.com/groups/gitlab-org/growth/product-intelligence/engineers/-/group_members?with_inherited_permissions=exclude) group for merge requests
 that are not drafts.