Add latest changes from gitlab-org/gitlab@master

1 files changed, 75 insertions, 66 deletions

diff --git a/doc/user/project/insights/index.md b/doc/user/project/insights/index.md
index 1107e91c33e..8e08d82c067 100644
--- a/doc/user/project/insights/index.md
+++ b/doc/user/project/insights/index.md
@@ -95,8 +95,9 @@ The following table lists the chart parameters:
 
 ### `title`
 
-`title` is the title of the chart as it displays on the Insights page.
-For example:
+Use `title` to update the chart title. The title displays on the insights report.
+
+**Example:**
 
 ```yaml
 monthlyBugsCreated:
@@ -105,8 +106,9 @@ monthlyBugsCreated:
 
 ### `description`
 
-The `description` text is displayed above the chart, but below the title. It's used
-to give extra details regarding the chart, for example:
+Use `description` to add a description of the chart. The description displays above the chart, below the title.
+
+**Example:**
 
 ```yaml
 monthlyBugsCreated:
@@ -116,33 +118,32 @@ monthlyBugsCreated:
 
 ### `type`
 
-`type` is the chart type.
+Use `type` to define the chart type.
 
-For example:
+**Supported values:**
 
-```yaml
-monthlyBugsCreated:
-  title: "Monthly bugs created"
-  type: bar
-```
-
-Supported values are:
-
-| Name  | Example |
+| Name  | Example: |
 | ----- | ------- |
 | `bar` | ![Insights example bar chart](img/insights_example_bar_chart.png) |
 | `bar` (time series, that is when `group_by` is used) | ![Insights example bar time series chart](img/insights_example_bar_time_series_chart.png) |
 | `line` | ![Insights example stacked bar chart](img/insights_example_line_chart.png) |
 | `stacked-bar` | ![Insights example stacked bar chart](img/insights_example_stacked_bar_chart.png) |
 
-NOTE:
-The `dora` data source supports the `bar` and `line` chart types.
+The `dora` data source supports the `bar` and `line` [chart types](#type).
+
+**Example:**
+
+```yaml
+monthlyBugsCreated:
+  title: "Monthly bugs created"
+  type: bar
+```
 
 ### `query`
 
-`query` allows to define the data source and various filtering conditions for the chart.
+Use `query` to define the data source and filtering conditions for the chart.
 
-Example:
+**Example:**
 
 ```yaml
 monthlyBugsCreated:
@@ -190,46 +191,46 @@ monthlyBugsCreated:
 
 > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/725) in GitLab 15.3.
 
-The `data_source` parameter was introduced to allow visualizing data from different data sources.
+Use `data_source` to define the data source that exposes the data.
 
-Supported values are:
+**Supported values:**
 
 - `issuables`: Exposes merge request or issue data.
-- `dora`: Exposes DORA metrics data.
+- `dora`: Exposes DORA metrics.
 
-#### `Issuable` query parameters
+#### `issuable` query parameters
 
 ##### `query.params.issuable_type`
 
-Defines the type of "issuable" you want to create a chart for.
+Use `query.params.issuable_type` to define the type of issuable to create a chart for.
 
-Supported values are:
+**Supported values:**
 
 - `issue`: The chart displays issues' data.
 - `merge_request`: The chart displays merge requests' data.
 
 ##### `query.params.issuable_state`
 
-Filter by the current state of the queried "issuable".
+Use `query.params.issuable_state` to filter by the current state of the queried issuable.
 
 By default, the `opened` state filter is applied.
 
-Supported values are:
+**Supported values:**
 
-- `opened`: Open issues / merge requests.
-- `closed`: Closed Open issues / merge requests.
-- `locked`: Issues / merge requests that have their discussion locked.
+- `opened`: Open issues or merge requests.
+- `closed`: Closed issues or merge requests.
+- `locked`: Issues or merge requests that have their discussion locked.
 - `merged`: Merged merge requests.
-- `all`: Issues / merge requests in all states
+- `all`: Issues or merge requests in all states.
 
 ##### `query.params.filter_labels`
 
-Filter by labels currently applied to the queried "issuable".
+Use `query.params.filter_labels` to filter by labels applied to the queried issuable.
 
-By default, no labels filter is applied. All the defined labels must be
-currently applied to the "issuable" in order for it to be selected.
+By default, no label filter is applied. All defined labels must
+be applied to the issuable for it to be selected.
 
-Example:
+**Example:**:
 
 ```yaml
 monthlyBugsCreated:
@@ -247,12 +248,13 @@ monthlyBugsCreated:
 
 ##### `query.params.collection_labels`
 
-Group "issuable" by the configured labels.
+Use `query.params.collection_labels` to group issuables by the configured labels.
+Grouping is not applied by default.
 
-By default, no grouping is done. When using this keyword, you need to
-set `type` to either `line` or `stacked-bar`.
+When using this parameter, you must
+set `type` to `line` or `stacked-bar`.
 
-Example:
+**Example:**
 
 ```yaml
 weeklyBugsBySeverity:
@@ -274,9 +276,9 @@ weeklyBugsBySeverity:
 
 ##### `query.group_by`
 
-Define the X-axis of your chart.
+Use `query.group_by` to define the X-axis of the chart.
 
-Supported values are:
+**Supported values:**
 
 - `day`: Group data per day.
 - `week`: Group data per week.
@@ -284,11 +286,10 @@ Supported values are:
 
 ##### `query.period_limit`
 
-Define how far "issuables" are queried in the past (using the `query.period_field`).
+Use `query.period_limit` to define how far back in time to query issuables (using the `query.period_field`).
 
-The unit is related to the `query.group_by` you defined. For instance if you
-defined `query.group_by: 'day'`  then `query.period_limit: 365` would mean
-"Gather and display data for the last 365 days".
+The unit is related to the value defined in `query.group_by`. For example, if you
+defined `query.group_by: 'day'`, and `query.period_limit: 365`, the chart displays data from the last 365 days.
 
 By default, default values are applied depending on the `query.group_by`
 you defined.
@@ -301,9 +302,9 @@ you defined.
 
 #### `query.period_field`
 
-Define the timestamp field used to group "issuables".
+Use `query.period_field` to define the timestamp field by which to group issuables.
 
-Supported values are:
+**Supported values:**
 
 - `created_at` (default): Group data using the `created_at` field.
 - `closed_at`: Group data using the `closed_at` field (for issues only).
@@ -323,7 +324,9 @@ you may see `created_at` in place of `merged_at`. `created_at` is used instead.
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367248) in GitLab 15.3.
 
-An example DORA chart definition:
+Use DORA-specific queries with the `dora` data source to create a DORA chart definition.
+
+**Example:**
 
 ```yaml
 dora:
@@ -355,53 +358,59 @@ dora:
 
 ##### `query.metric`
 
-Defines which DORA metric to query. The available values are:
+Use `query.metric` to define the [DORA metrics](../../../api/dora/metrics.md#the-value-field) to query.
+
+**Supported values:**
 
 - `deployment_frequency` (default)
 - `lead_time_for_changes`
 - `time_to_restore_service`
 - `change_failure_rate`
 
-The metrics are described on the [DORA API](../../../api/dora/metrics.md#the-value-field) page.
-
 ##### `query.group_by`
 
-Define the X-axis of your chart.
+Use `query.group_by` to define the X-axis of your chart.
 
-Supported values are:
+**Supported values:**
 
 - `day` (default): Group data per day.
 - `month`: Group data per month.
 
 ##### `query.period_limit`
 
-Define how far the metrics are queried in the past (default: 15). Maximum lookback period is 180 days or 6 months.
+Use `query.period_limit` to define how far the metrics are queried in the past (default: 15). The maximum period is 180 days or 6 months.
 
 ##### `query.environment_tiers`
 
-An array of environments to include into the calculation (default: production). Available options: `production`, `staging`, `testing`, `development`, `other`.
+Use `query.environment_tiers` to define an array of environments to include the calculation.
+
+**Supported values:**
+
+- `production`(default)
+- `staging`
+- `testing`
+- `development`
+- `other`
 
 ### `projects`
 
-You can limit where the "issuables" can be queried from:
+Use `projects` to limit where issuables are queried from:
 
-- If `.gitlab/insights.yml` is used for a [group's insights](../../group/insights/index.md#configure-your-insights), with `projects`, you can limit the projects to be queried. By default, all projects currently under the group are used.
-- If `.gitlab/insights.yml` is used for a project's insights, specifying any other projects yields no results. By default, the project itself is used.
+- If `.gitlab/insights.yml` is used for a [group's insights](../../group/insights/index.md#configure-your-insights), use `projects` to define the projects from which to query issuables. By default, all projects under the group are used.
+- If `.gitlab/insights.yml` is used for a project's insights, specifying other projects does not yield results. By default, the project is used.
 
 #### `projects.only`
 
-The `projects.only` option specifies the projects which the "issuables"
-should be queried from.
+Use `projects.only` to specify the projects from which issuables
+are queried.
 
-Projects listed here are ignored when:
+Projects listed in this parameter are ignored when:
 
 - They don't exist.
 - The current user doesn't have sufficient permissions to read them.
-- They are outside of the group.
+- They are outside the group.
 
-In the following `insights.yml` example, we specify the projects
-the queries are used on. This example is useful when setting
-a group's insights:
+**Example:**
 
 ```yaml
 monthlyBugsCreated:
@@ -423,7 +432,7 @@ monthlyBugsCreated:
       - groupB/project            # Projects outside the group will be ignored
 ```
 
-## Complete example
+## Complete insights configuration example
 
 ```yaml
 .projectsOnly: &projectsOnly