Merge branch '9995-group-insights-documentation-docs' into 'master'

First iteration of the Insights feature documentation

Closes #9995

See merge request gitlab-org/gitlab-ee!10282

doc/user/group/index.md

@@ -204,6 +204,12 @@ Get an overview of the vulnerabilities of all the projects in a group and its su
 
 > Introduced in [GitLab Ultimate][ee] 11.9 behind the `insights` feature flag.
 
+Configure the Insights that matter for your groups or projects to explore data
+such as triage hygiene, issues created/closed per a given period, average time
+for merge requests to be merged and much more.
+
+[Learn more about Insights](insights/index.md).
+
 ## Transferring groups
 
 From GitLab 10.5, groups can be transferred in the following ways:

doc/user/group/insights/index.md

+# Insights **[ULTIMATE]**
+
+> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.9 behind the `insights` feature flag.
+
+CAUTION: **Beta:**
+Insights is considered beta, and is not ready for production use.
+Follow [gitlab-org&725](https://gitlab.com/groups/gitlab-org/-/epics/725) for
+updates.
+
+Configure the Insights that matter for your groups to explore data such as
+triage hygiene, issues created/closed per a given period, average time for merge
+requests to be merged and much more.
+
+![Insights example stacked bar chart](img/insights_example_stacked_bar_chart.png)
+
+## Configure your Insights
+
+Navigate to your group's **Settings > General**, expand **Insights**, and choose
+the project that holds your `.gitlab/insights.yml` configuration file:
+
+![group insights configuration](img/insights_group_configuration.png)
+
+See the [Project's Insights documentation](../../project/insights/index.md) for
+more details about the `.gitlab/insights.yml` configuration file.
+
+## Permissions
+
+If you have access to view a group, then you have access to view their Insights.
+
+NOTE: **Note:**
+Issues or merge requests that you don't have access to (because you don't have
+access to the project they belong to, or because they are confidential) are
+filtered out of the Insights charts.
+
+You may also consult the [group permissions table](../../permissions.md#group-members-permissions).

doc/user/permissions.md

@@ -120,6 +120,7 @@ The following table depicts the various user permission levels in a project.
 | Remove protected branches [^4]        |         |            |             |          |        |
 | View project Audit Events             |         |            |             | ✓        | ✓      |
 | View project statistics               |         | ✓          | ✓           | ✓        | ✓      |
+| View Insights charts **[ULTIMATE]**   | ✓       | ✓         | ✓           | ✓        | ✓      |
 
 ## Project features permissions
 
@@ -200,6 +201,7 @@ group.
 | Create/edit group epic **[ULTIMATE]**  |         | ✓        | ✓         | ✓      | ✓     |
 | Delete group epic **[ULTIMATE]**       |         |          |           |        | ✓     |
 | View group Audit Events  |         |          |           |        | ✓     |
+| View Insights charts **[ULTIMATE]** | ✓       | ✓         | ✓           | ✓        | ✓      |
 
 ### Subgroup permissions
 

doc/user/project/insights/index.md

+# Insights **[ULTIMATE]**
+
+> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.9 behind the `insights` feature flag.
+
+CAUTION: **Beta:**
+Insights is considered beta, and is not ready for production use.
+Follow [gitlab-org&725](https://gitlab.com/groups/gitlab-org/-/epics/725) for
+updates.
+
+Configure the Insights that matter for your projects to explore data such as
+triage hygiene, issues created/closed per a given period, average time for merge
+requests to be merged and much more.
+
+![Insights example stacked bar chart](img/insights_example_stacked_bar_chart.png)
+
+NOTE: **Note:**
+This feature is [also available at the group level](../../group/insights/index.md).
+
+## Configure your Insights
+
+Insights are configured using a YAML file called `.gitlab/insights.yml` within
+a project. That file will then be used in the project's Insights page.
+
+See [Writing your `.gitlab/insights.yml`](#writing-your-gitlabinsightsyml) below
+for details about the content of this file.
+
+NOTE: **Note:**
+Once the configuration file is created, you can also
+[use it for your project's group](../../group/insights/index.md#configure-your-insights).
+
+## Permissions
+
+If you have access to view a project, then you have access to view their
+Insights.
+
+NOTE: **Note:**
+Issues or merge requests that you don't have access to (because you don't have
+access to the project they belong to, or because they are confidential) are
+filtered out of the Insights charts.
+
+You may also consult the [group permissions table](../../permissions.md#group-members-permissions).
+
+## Writing your `.gitlab/insights.yml`
+
+The `.gitlab/insights.yml` file defines the structure and order of the Insights
+charts that will be displayed in the Insights page of your project or group.
+
+Each chart have a unique key, and a definition hash composed of key-value pairs.
+
+For example, here's single chart definition:
+
+```yaml
+monthlyBugsCreated:
+  title: Monthly Bugs Created (bar)
+  type: bar
+  query:
+    issuable_type: issue
+    issuable_state: opened
+    filter_labels:
+      - bug
+    group_by: month
+    period_limit: 24
+```
+
+## Configuration parameters
+
+A chart is defined as a list of parameters that define the chart's behavior.
+
+The following table lists available parameters for charts:
+
+| Keyword                                            | Description |
+|:---------------------------------------------------|:------------|
+| [`title`](#title)                                  | The title of the chart. This will displayed on the Insights page. |
+| [`type`](#type)                                    | The type of chart: `bar`, `line`, `stacked-bar`, `pie` etc. |
+| [`query`](#query)                                  | A hash that defines the conditions for issues / merge requests to be part of the chart. |
+
+## Parameter details
+
+The following are detailed explanations for parameters used to configure
+Insights charts.
+
+### `title`
+
+`title` is the title of the chart as it will be displayed on the Insights page.
+For example:
+
+```yaml
+monthlyBugsCreated:
+  title: Monthly Bugs Created (bar)
+```
+
+### `type`
+
+`type` is the chart type.
+
+For example:
+
+```yaml
+monthlyBugsCreated:
+  title: Monthly Bugs Created (bar)
+  type: bar
+```
+
+Supported values are:
+
+| Name  | Example |
+| ----- | ------- |
+| `bar` | ![Insights example stacked bar chart](img/insights_example_bar_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) |
+
+### `query`
+
+`query` allows to define the conditions for issues / merge requests to be part
+of the chart.
+
+Example:
+
+```yaml
+monthlyBugsCreated:
+  title: Monthly Bugs Created (bar)
+  type: bar
+  query:
+    issuable_type: issue
+    issuable_state: opened
+    filter_labels:
+      - bug
+    collection_labels:
+      - S1
+      - S2
+      - S3
+      - S4
+    group_by: week
+    period_limit: 104
+```
+
+#### `query.issuable_type`
+
+Defines the type of "issuable" you want to create a chart for.
+
+Supported values are:
+
+- `issue`: The chart will display issues' data.
+- `merge_request`: The chart will display merge requests' data.
+
+#### `query.issuable_state`
+
+Filter by the state of the queried "issuable".
+
+If you omit it, no state filter will be applied.
+
+Supported values are:
+
+- `opened`: Open issues / merge requests.
+- `closed`: Closed Open issues / merge requests.
+- `locked`: Issues / merge requests that have their discussion locked.
+- `merged`: Merged merge requests.
+
+#### `query.filter_labels`
+
+Filter by labels applied to the queried "issuable".
+
+If you omit it, no labels filter will be applied. All the defined labels must be
+applied to the "issuable" in order for it to be selected.
+
+Example:
+
+```yaml
+monthlyBugsCreated:
+  title: Monthly regressions Created (bar)
+  type: bar
+  query:
+    issuable_type: issue
+    issuable_state: opened
+    filter_labels:
+      - bug
+      - regression
+```
+
+#### `query.collection_labels`
+
+Group "issuable" by the configured labels.
+
+If you omit it, no grouping will be done. When using this keyword, you need to
+set `type` to either `line` or `stacked-bar`.
+
+Example:
+
+```yaml
+weeklyBugsBySeverity:
+  title: Weekly Bugs By Severity (stacked bar)
+  type: stacked-bar
+  query:
+    issuable_type: issue
+    issuable_state: opened
+    filter_labels:
+      - bug
+    collection_labels:
+      - S1
+      - S2
+      - S3
+      - S4
+```
+
+#### `query.group_by`
+
+Define the X-axis of your chart.
+
+Supported values are:
+
+- `day`: Group data per day.
+- `week`: Group data per week.
+- `month`: Group data per month.
+
+#### `query.period_limit`
+
+Define how far "issuables" are queried in the past.
+
+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".
+
+If you omit it, default values will be applied depending on the `query.group_by`
+you defined.
+
+| `query.group_by` | Default value |
+| ---------------- | ------------- |
+| `day`            | 30            |
+| `week`           | 4             |
+| `month`          | 12            |
+
+## Complete example
+
+```yaml
+monthlyBugsCreated:
+  title: Monthly Bugs Created (bar)
+  type: bar
+  query:
+    issuable_type: issue
+    issuable_state: opened
+    filter_labels:
+      - bug
+    group_by: month
+    period_limit: 24
+weeklyBugsBySeverity:
+  title: Weekly Bugs By Severity (stacked bar)
+  type: stacked-bar
+  query:
+    issuable_type: issue
+    issuable_state: opened
+    filter_labels:
+      - bug
+    collection_labels:
+      - S1
+      - S2
+      - S3
+      - S4
+    group_by: week
+    period_limit: 104
+monthlyBugsByTeamLine:
+  title: Monthly Bugs By Team (line)
+  type: line
+  query:
+    issuable_type: merge_request
+    issuable_state: opened
+    filter_labels:
+      - bug
+    collection_labels:
+      - Manage
+      - Plan
+      - Create
+    group_by: month
+    period_limit: 24
+```