Shift information on the dashboard page

Move the info on the dashboard page to the top of the page, in
prep for changing subheadings.

app/views/projects/blob/viewers/_metrics_dashboard_yml.html.haml

@@ -8,4 +8,4 @@
     - viewer.errors.messages.each do |error|
       %li= error.join(': ')
 
-= link_to _('Learn more'), help_page_path('operations/metrics/dashboards/index.md', anchor: 'defining-custom-dashboards-per-project')
+= link_to _('Learn more'), help_page_path('operations/metrics/dashboards/index.md')

doc/administration/monitoring/gitlab_self_monitoring_project/index.md

@@ -58,7 +58,7 @@ The dashboard uses metrics available in
 ![GitLab self monitoring default dashboard](img/self_monitoring_default_dashboard.png)
 
 You can also
-[create your own dashboards](../../../operations/metrics/dashboards/index.md#defining-custom-dashboards-per-project).
+[create your own dashboards](../../../operations/metrics/dashboards/index.md).
 
 ## Connection to Prometheus
 
@@ -83,8 +83,8 @@ Once the webhook is setup, you can
 
 You can add custom metrics in the self monitoring project by:
 
-1. [Duplicating](../../../operations/metrics/dashboards/index.md#duplicating-a-gitlab-defined-dashboard) the default dashboard.
-1. [Editing](../../../operations/metrics/dashboards/index.md#view-and-edit-the-source-file-of-a-custom-dashboard) the newly created dashboard file and configuring it with [dashboard YAML properties](../../../operations/metrics/dashboards/yaml.md).
+1. [Duplicating](../../../operations/metrics/dashboards/index.md#duplicate-a-gitlab-defined-dashboard) the default dashboard.
+1. [Editing](../../../operations/metrics/index.md) the newly created dashboard file and configuring it with [dashboard YAML properties](../../../operations/metrics/dashboards/yaml.md).
 
 ## Troubleshooting
 

doc/operations/metrics/dashboards/index.md

@@ -4,61 +4,129 @@ group: APM
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
 ---
 
-# Using the Metrics Dashboard
+# Custom dashboards
 
-## Manage the metrics dashboard settings
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/59974) in GitLab 12.1.
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223204) in GitLab 13.2.
+By default, all projects include a GitLab-defined Prometheus dashboard, which
+includes a few key metrics, but you can also define your own custom dashboards.
 
-To manage the settings for your metrics dashboard:
+You may create a [new dashboard from scratch](#add-a-new-dashboard-to-your-project)
+or [duplicate a GitLab-defined Prometheus dashboard](#duplicate-a-gitlab-defined-dashboard).
 
-1. Sign in as a user with project Maintainer or Admin
+NOTE: **Note:**
+The metrics as defined below do not support alerts, unlike
+[custom metrics](../index.md#adding-custom-metrics).
+
+## Add a new dashboard to your project
+
+> UI option [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223204) in GitLab 13.2.
+
+You can configure a custom dashboard by adding a new YAML file into your project's
+`.gitlab/dashboards/` directory. For the dashboard to display on your project's
+**{cloud-gear}** **Operations > Metrics** page, the files must have a `.yml`
+extension and be present in your project's **default** branch.
+
+To create a new dashboard from the GitLab user interface:
+
+1. Sign in to GitLab as a user with Maintainer or Owner
    [permissions](../../../user/permissions.md#project-members-permissions).
 1. Navigate to your dashboard at **{cloud-gear}** **Operations > Metrics**.
-1. In the top-right corner of your dashboard, click **{settings}** **Metrics Settings**:
+1. In the top-right corner of your dashboard, click the **{file-addition-solid}** **Actions** menu,
+   and select **Create new**:
+   ![Monitoring Dashboard actions menu with create new item](../../../user/project/integrations/img/actions_menu_create_new_dashboard_v13_2.png)
+1. In the modal window, click **Open Repository**, then follow the instructions
+   for creating a new dashboard from the command line.
 
-   ![Monitoring Dashboard actions menu with create new item](../../../user/project/integrations/img/metrics_settings_button_v13_2.png)
+To create a new dashboard from the command line:
 
-## Chart Context Menu
+1. Create `.gitlab/dashboards/prom_alerts.yml` under your repository's root
+   directory. Each YAML file should define the layout of the dashboard and the
+   Prometheus queries used to populate data. This example dashboard displays a
+   single area chart:
+
+   ```yaml
+   dashboard: 'Dashboard Title'
+   panel_groups:
+     - group: 'Group Title'
+       panels:
+         - type: area-chart
+           title: "Chart Title"
+           y_label: "Y-Axis"
+           y_axis:
+             format: number
+             precision: 0
+           metrics:
+             - id: my_metric_id
+               query_range: 'http_requests_total'
+               label: "Instance: {{instance}}, method: {{method}}"
+               unit: "count"
+   ```
 
-From each of the panels in the dashboard, you can access the context menu by clicking the **{ellipsis_v}** **More actions** dropdown box above the upper right corner of the panel to take actions related to the chart's data.
+1. Save the file, commit, and push to your repository. The file must be present in your **default** branch.
+1. Navigate to your project's **Operations > Metrics** and choose the custom
+   dashboard from the dropdown.
 
-![Context Menu](../../../user/project/integrations/img/panel_context_menu_v13_0.png)
+Your custom dashboard is available at `https://example.com/project/-/metrics/custom_dashboard_name.yml`.
 
-The options are:
+NOTE: **Note:**
+Configuration files nested under subdirectories of `.gitlab/dashboards` are not
+supported and won't be available in the UI.
 
-- [Expand panel](#expand-panel)
-- [View logs](#view-logs-ultimate)
-- [Download CSV](#downloading-data-as-csv)
-- [Copy link to chart](../embed.md#embedding-gitlab-managed-kubernetes-metrics)
-- [Alerts](../alerts.md)
+## Duplicate a GitLab-defined dashboard
 
-### View and edit the source file of a custom dashboard
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/37238) in GitLab 12.7.
+> - From [GitLab 12.8 onwards](https://gitlab.com/gitlab-org/gitlab/-/issues/39505), custom metrics are also duplicated when you duplicate a dashboard.
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34779) in GitLab 12.5.
+You can save a complete copy of a GitLab defined dashboard along with all custom metrics added to it.
+The resulting `.yml` file can be customized and adapted to your project.
+You can decide to save the dashboard `.yml` file in the project's **default** branch or in a
+new branch.
+
+1. Click **Duplicate dashboard** in the dashboard dropdown or in the actions menu.
+
+   NOTE: **Note:**
+   You can duplicate only GitLab-defined dashboards.
+
+1. Enter the filename and other information, such as the new commit's message, and click **Duplicate**.
+1. Select a branch to add your dashboard to:
+   - *If you select your **default** branch,* the new dashboard becomes immediately available.
+   - *If you select another branch,* this branch should be merged to your **default** branch first.
 
-When viewing a custom dashboard of a project, you can view the original
-`.yml` file by clicking on the **Edit dashboard** button.
+Your custom dashboard is available at `https://example.com/project/-/metrics/custom_dashboard_name.yml`.
+
+## Manage the metrics dashboard settings
 
-### Expand panel
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223204) in GitLab 13.2.
 
-> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3100) in GitLab 13.0.
+To manage the settings for your metrics dashboard:
 
-To view a larger version of a visualization, expand the panel by clicking the
-**{ellipsis_v}** **More actions** icon and selecting **Expand panel**.
+1. Sign in as a user with project Maintainer or Admin
+   [permissions](../../../user/permissions.md#project-members-permissions).
+1. Navigate to your dashboard at **{cloud-gear}** **Operations > Metrics**.
+1. In the top-right corner of your dashboard, click **{settings}** **Metrics Settings**:
 
-To return to the metrics dashboard, click the **Back** button in your
-browser, or pressing the <kbd>Esc</kbd> key.
+   ![Monitoring Dashboard actions menu with create new item](../../../user/project/integrations/img/metrics_settings_button_v13_2.png)
 
-### View Logs **(ULTIMATE)**
+## Chart Context Menu
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/122013) in GitLab 12.8.
+You can take action related to a chart's data by clicking the
+**{ellipsis_v}** **More actions** dropdown box above the upper right corner of
+any chart on a dashboard:
 
-If you have [Logs](../../../user/project/clusters/kubernetes_pod_logs.md) enabled,
-you can navigate from the charts in the dashboard to view Logs by
-clicking on the context menu in the upper-right corner.
+![Context Menu](../../../user/project/integrations/img/panel_context_menu_v13_0.png)
 
-If you use the **Timeline zoom** function at the bottom of the chart, logs will narrow down to the time range you selected.
+The options are:
+
+- **Expand panel** - Displays a larger version of a visualization. To return to
+  the dashboard, click the **Back** button in your browser, or press the <kbd>Esc</kbd> key.
+  ([Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3100) in GitLab 13.0.)
+- **View logs** **(ULTIMATE)** - Displays [Logs](../../../user/project/clusters/kubernetes_pod_logs.md),
+  if they are enabled. If used in conjunction with the [timeline zoom](#timeline-zoom-and-url-sharing)
+  feature, logs narrow down to the selected time range. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/122013) in GitLab 12.8.)
+- **Download CSV** - Data from Prometheus charts on the metrics dashboard can be downloaded as CSV.
+- [Copy link to chart](../embed.md#embedding-gitlab-managed-kubernetes-metrics)
+- [Alerts](../alerts.md)
 
 ### Timeline zoom and URL sharing
 
@@ -69,10 +137,6 @@ on a date and time of your choice. When you click and drag the sliders to select
 a different beginning or end date of data to display, GitLab adds your selected start
 and end times to the URL, enabling you to share specific timeframes more easily.
 
-### Downloading data as CSV
-
-Data from Prometheus charts on the metrics dashboard can be downloaded as CSV.
-
 ## Dashboard Annotations
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211330) in GitLab 12.10 (enabled by feature flag `metrics_dashboard_annotations`).
@@ -90,7 +154,7 @@ You can create annotations by making requests to the
 
 ![Annotations UI](../../../user/project/integrations/img/metrics_dashboard_annotations_ui_v13.0.png)
 
-### Retention policy
+### Annotation retention policy
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211433) in GitLab 13.01.
 
@@ -139,99 +203,6 @@ links:
     type: grafana
 ```
 
-## Defining custom dashboards per project
-
-> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/59974) in GitLab 12.1.
-
-By default, all projects include a GitLab-defined Prometheus dashboard, which
-includes a few key metrics, but you can also define your own custom dashboards.
-
-You may create a new file from scratch or duplicate a GitLab-defined Prometheus
-dashboard.
-
-NOTE: **Note:**
-The metrics as defined below do not support alerts, unlike
-[custom metrics](../index.md#adding-custom-metrics).
-
-### Adding a new dashboard to your project
-
-> UI option [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223204) in GitLab 13.2.
-
-You can configure a custom dashboard by adding a new YAML file into your project's
-`.gitlab/dashboards/` directory. In order for the dashboards to be displayed on
-the project's **{cloud-gear}** **Operations > Metrics** page, the files must have a `.yml`
-extension and should be present in the project's **default** branch.
-
-To create a new dashboard from the GitLab user interface:
-
-1. Sign in to GitLab as a user with Maintainer or Owner
-   [permissions](../../../user/permissions.md#project-members-permissions).
-1. Navigate to your dashboard at **{cloud-gear}** **Operations > Metrics**.
-1. In the top-right corner of your dashboard, click the **{file-addition-solid}** **Actions** menu,
-   and select **Create new**:
-   ![Monitoring Dashboard actions menu with create new item](../../../user/project/integrations/img/actions_menu_create_new_dashboard_v13_2.png)
-1. In the modal window, click **Open Repository**, then follow the instructions
-   for creating a new dashboard from the command line.
-
-To create a new dashboard from the command line:
-
-1. Create `.gitlab/dashboards/prom_alerts.yml` under your repository's root
-   directory. Each YAML file should define the layout of the dashboard and the
-   Prometheus queries used to populate data. This example dashboard displays a
-   single area chart:
-
-   ```yaml
-   dashboard: 'Dashboard Title'
-   panel_groups:
-     - group: 'Group Title'
-       panels:
-         - type: area-chart
-           title: "Chart Title"
-           y_label: "Y-Axis"
-           y_axis:
-             format: number
-             precision: 0
-           metrics:
-             - id: my_metric_id
-               query_range: 'http_requests_total'
-               label: "Instance: {{instance}}, method: {{method}}"
-               unit: "count"
-   ```
-
-1. Save the file, commit, and push to your repository. The file must be present in your **default** branch.
-1. Navigate to your project's **Operations > Metrics** and choose the custom
-   dashboard from the dropdown.
-
-NOTE: **Note:**
-Configuration files nested under subdirectories of `.gitlab/dashboards` are not
-supported and will not be available in the UI.
-
-### Navigating to a custom dashboard
-
-Custom dashboards are uniquely identified by their filenames. In order to quickly view the custom dashboard,
-just use the dashboard filename in the URL this way:
-`https://gitlab-instance.example.com/project/-/metrics/custom_dashboard_name.yml`.
-
-### Duplicating a GitLab-defined dashboard
-
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/37238) in GitLab 12.7.
-> - From [GitLab 12.8 onwards](https://gitlab.com/gitlab-org/gitlab/-/issues/39505), custom metrics are also duplicated when you duplicate a dashboard.
-
-You can save a complete copy of a GitLab defined dashboard along with all custom metrics added to it.
-Resulting `.yml` file can be customized and adapted to your project.
-You can decide to save the dashboard `.yml` file in the project's **default** branch or in a
-new branch.
-
-1. Click **Duplicate dashboard** in the dashboard dropdown or in the actions menu.
-
-   NOTE: **Note:**
-   You can duplicate only GitLab-defined dashboards.
-
-1. Enter the file name and other information, such as the new commit's message, and click **Duplicate**.
-
-If you select your **default** branch, the new dashboard becomes immediately available.
-If you select another branch, this branch should be merged to your **default** branch first.
-
 ## Troubleshooting
 
 When troubleshooting issues with a managed Prometheus app, it is often useful to

doc/operations/metrics/embed.md

@@ -53,7 +53,7 @@ Metric charts may also be hidden:
 ![Show Hide](../../user/project/integrations/img/hide_embedded_metrics_v12_10.png)
 
 You can open the link directly into your browser for a
-[detailed view of the data](dashboards/index.md#expand-panel).
+[detailed view of the data](dashboards/index.md#chart-context-menu).
 
 ## Embedding metrics in issue templates
 

doc/operations/metrics/index.md

@@ -41,8 +41,11 @@ navigation bar contains:
   Starred dashboards display a solid star **{star}** button, and display first
   in the **Dashboard** dropdown list.
   ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214582) in GitLab 13.0.)
+- **Edit dashboard** - Edit the source YAML file of a custom dashboard. Only available on
+  [custom dashboards](dashboards/index.md).
+  ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34779) in GitLab 12.5.)
 - **Create dashboard** **{file-addition-solid}** - Create a
-  [new custom dashboard for your project](dashboards/index.md#adding-a-new-dashboard-to-your-project).
+  [new custom dashboard for your project](dashboards/index.md#add-a-new-dashboard-to-your-project).
 - **Metrics settings** **{settings}** - Configure the
   [settings for this dashboard](dashboards/index.md#manage-the-metrics-dashboard-settings).
 

doc/user/incident_management/index.md

@@ -105,11 +105,8 @@ in incidents and issue templates.
 
 You can view more details about an embedded metrics panel from the context menu.
 To access the context menu, click the **{ellipsis_v}** **More actions** dropdown box
-above the upper right corner of the panel. The options are:
-
-- [View logs](#view-logs-from-metrics-panel).
-- **Download CSV** - Data from embedded charts can be
-  [downloaded as CSV](../../operations/metrics/dashboards/index.md#downloading-data-as-csv).
+above the upper right corner of the panel. For a list of options, see
+[Chart context menu](../../operations/metrics/dashboards/index.md#chart-context-menu).
 
 #### View logs from metrics panel
 
@@ -117,7 +114,7 @@ above the upper right corner of the panel. The options are:
 > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25455) to [GitLab Core](https://about.gitlab.com/pricing/) 12.9.
 
 Viewing logs from a metrics panel can be useful if you're triaging an application
-incident and need to [explore logs](../../operations/metrics/dashboards/index.md#view-logs-ultimate)
+incident and need to [explore logs](../../operations/metrics/dashboards/index.md#chart-context-menu)
 from across your application. These logs help you understand what is affecting
 your application's performance and resolve any problems.
 

doc/user/project/integrations/prometheus.md

@@ -121,7 +121,8 @@ one of them will be used:
   [Prometheus manual configuration](#manual-configuration-of-prometheus)
   and a [managed Prometheus on Kubernetes](#managed-prometheus-on-kubernetes),
   the manual configuration takes precedence and is used to run queries from
-  [dashboards](../../../operations/metrics/dashboards/index.md#defining-custom-dashboards-per-project) and [custom metrics](../../../operations/metrics/index.md#adding-custom-metrics).
+  [custom dashboards](../../../operations/metrics/dashboards/index.md) and
+  [custom metrics](../../../operations/metrics/index.md#adding-custom-metrics).
 - If you have managed Prometheus applications installed on Kubernetes clusters
   at **different** levels (project, group, instance), the order of precedence is described in
   [Cluster precedence](../../instance/clusters/index.md#cluster-precedence).