From a6ef2cda29ea680891c3b54cb499427be5cb15a2 Mon Sep 17 00:00:00 2001
From: achatterjee-grafana
 <70489351+achatterjee-grafana@users.noreply.github.com>
Date: Tue, 5 Oct 2021 20:41:20 -0400
Subject: [PATCH] Doc: Fix escalation issue 903 (#40034) (#40036)

* First set of reorg of Playlist topic. Also fixed a broken bookmark in Azure authentication topic.

* More re-org.

* Added note requested in issue 903.

* Updated a note added dashboard HTTP API endpoint.

* Update docs/sources/dashboards/playlist.md

Co-authored-by: Fiona Artiaga <89225282+GrafanaWriter@users.noreply.github.com>

* Update docs/sources/dashboards/playlist.md

Co-authored-by: Fiona Artiaga <89225282+GrafanaWriter@users.noreply.github.com>

* Update docs/sources/dashboards/playlist.md

Co-authored-by: Fiona Artiaga <89225282+GrafanaWriter@users.noreply.github.com>

* Update docs/sources/dashboards/playlist.md

Co-authored-by: Fiona Artiaga <89225282+GrafanaWriter@users.noreply.github.com>

* Update docs/sources/dashboards/playlist.md

Co-authored-by: Fiona Artiaga <89225282+GrafanaWriter@users.noreply.github.com>

* Update docs/sources/dashboards/playlist.md

Co-authored-by: Fiona Artiaga <89225282+GrafanaWriter@users.noreply.github.com>

* Updated image position and name.

Co-authored-by: Fiona Artiaga <89225282+GrafanaWriter@users.noreply.github.com>

Co-authored-by: Fiona Artiaga <89225282+GrafanaWriter@users.noreply.github.com>
---
 docs/sources/auth/azuread.md        |   2 +-
 docs/sources/dashboards/playlist.md | 161 ++++++++++------------------
 docs/sources/http_api/dashboard.md  |   2 +-
 3 files changed, 58 insertions(+), 107 deletions(-)

diff --git a/docs/sources/auth/azuread.md b/docs/sources/auth/azuread.md
index 7c93f79b1fc..7323f90dad7 100644
--- a/docs/sources/auth/azuread.md
+++ b/docs/sources/auth/azuread.md
@@ -10,7 +10,7 @@ weight = 700
 The Azure AD authentication allows you to use an Azure Active Directory tenant as an identity provider for Grafana. You can use Azure AD Application Roles to assign users and groups to Grafana roles from the Azure Portal. This topic has the following sections:
 
 - [Create the Azure AD application](#create-the-azure-ad-application)
-- [Enable Azure AD OAuth in Grafana](/#enable-azure-ad-oauth-in-grafana)
+- [Enable Azure AD OAuth in Grafana](#enable-azure-ad-oauth-in-grafana)
 
 ## Create the Azure AD application
 
diff --git a/docs/sources/dashboards/playlist.md b/docs/sources/dashboards/playlist.md
index 404b9e08146..51bea340289 100644
--- a/docs/sources/dashboards/playlist.md
+++ b/docs/sources/dashboards/playlist.md
@@ -7,121 +7,42 @@ weight = 4
 
 # Playlist
 
-A playlist is a list of dashboards that are displayed in a sequence. You might use a playlist to build situational awareness or to present your metrics to your team or visitors.
+A playlist displays a list of dashboards that are in a sequence. Use a playlist to build situational awareness or to present your metrics to your team or visitors. Grafana automatically scales dashboards to any resolution, which makes them perfect for big screens. This topic has the following sections:
 
-Grafana automatically scales dashboards to any resolution, which makes them perfect for big screens.
+- [Access, share, and control a playlist](#access-share-and-control-a-playlist)
+- [Create a playlist](#create-a-playlist)
+- [Edit or delete a playlist](#edit-or-delete-a-playlist)
+- [Share a playlist](#share-a-playlist-in-a-view-mode)
 
-You can access the Playlist feature from Grafana's side menu, in the Dashboards submenu.
+## Access, share, and control a playlist
 
-{{< figure src="/static/img/docs/v50/playlist.png" max-width="25rem">}}
+Use the information in this section to access existing playlists. Start and control the display of a playlist using one of the five available modes.
 
-## Create a playlist
+### Access playlist
 
-You create a playlist to present dashboards in a sequence, with a set order and time interval between dashboards.
+1. Hover your cursor over Grafana’s side menu.
+1. Click **Playlists**. You will see a list of existing playlists.
 
-1. To access the Playlist feature, hover your cursor over Grafana's side menu.
-1. Click **Playlists**.
-1. Click **New playlist**.
-1. In the **Name** text box, enter a name for your playlist.
-1. In the **Interval** text box, enter a time interval.
+### Start a playlist
 
-The time interval is the amount of time for Grafana to stay on a particular dashboard before advancing to the next one on the playlist.
+1. [Access](#access-playlist) the playlist page to see a list of existing playlists.
+1. Find the playlist you want to start, then click **Start playlist**. The start playlist dialog opens.
+1. Select one of the five playlist modes available based on the information in the following table.
+1. Click **Start <playlist name>**.
 
-1. Next to the dashboard(s) you want to add to your playlist, click **Add to playlist**.
-1. Click **Create**.
+The playlist displays each dashboard for the time specified in the `Interval` field, set when creating or editing a playlist. Once a playlist starts, you can [control](#control-a-playlist) it using the navbar at the top of your screen.
 
-## Edit a playlist
+| Mode                              | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Normal mode                       | <ul><li>The side menu remains visible.</li></ul><ul><li>The navbar, row, and panel controls appear at the top of the screen.</li></ul>                                                                                                                                                                                                                                                                                                                                                                            |
+| TV mode                           | <ul><li>The side menu and dashboard submenu (including variable drop-downs and dashboard links) are hidden or removed.</li></ul><ul><li>The navbar, row, and panel controls appear at the top of the screen.</li></ul><ul><li>Enabled automatically after one minute of user inactivity.</li></ul><ul><li>Enable it manually using the `d v` sequence shortcut, or by appending the parameter `?inactive` to the dashboard URL.</li></ul><ul><li>Disable it with any mouse movement or keyboard action.</li></ul> |
+| TV mode (with auto fit panels)    | <ul><li>The side menu and dashboard submenu (including variable drop-downs and dashboard links) are hidden or removed.</li></ul><ul><li>The navbar, row and panel controls appear at the top of the screen.</li></ul><ul><li>Dashboard panels automatically adjust to optimize space on screen.</li></ul><ul>                                                                                                                                                                                                     |
+| Kiosk mode                        | <ul><li>The side menu, navbar, ro and panel controls are completely hidden/removed from view.</li></ul><ul><li>You can enable it manually using the `d v` sequence shortcut after the playlist has started.</li></ul><ul><li>You can disable it manually with the same shortcut.</li></ul>                                                                                                                                                                                                                        |
+| Kiosk mode (with auto fit panels) | <ul><li>The side menu, navbar, row, and panel controls are completely hidden/removed from view.</li></ul><ul><li>Dashboard panels automatically adjust to optimize space on screen.</li></ul>                                                                                                                                                                                                                                                                                                                     |
 
-You can edit playlists while creating them or after saving them.
+### Control a playlist
 
-1. To access the Playlist feature, hover your cursor over Grafana's side menu.
-1. Click **Playlists**.
-1. Click on the Playlist that you want to edit.
-
-### Edit the Name of a playlist
-
-1. Double-click within the **Name** text box.
-1. Enter a name.
-1. Click **Save** to save your changes.
-
-### Edit the Interval of a playlist
-
-1. Double-click within the **Interval** text box.
-1. Enter a time interval.
-1. Click **Save** to save your changes.
-
-### Add a dashboard to a playlist
-
-1. Next to the dashboard you want to add, click **Add to playlist**.
-1. Click **Save** to save your changes.
-
-### Search for a dashboard to add
-
-1. Click the **Search dashboards by name** text box.
-1. Search for the playlist by name or regular expression.
-1. If needed, filter your results by starred status or tags.
-   By default, your starred dashboards will appear as options to add to the Playlist.
-1. Click **Save** to save your changes.
-
-### Rearrange dashboard order
-
-1. Next to the dashboard you want to move, click the up or down arrow.
-1. Click **Save** to save your changes.
-
-### Remove a dashboard
-
-1. Click **Remove[x]** to remove a dashboard from the playlist.
-1. Click **Save** to save your changes.
-
-### Delete a playlist
-
-1. Click **Playlists**.
-1. Next to the Playlist you want to delete, click **Remove[x]**.
-
-## Save a playlist
-
-You can save a playlist to add it to your **Playlists** page, where you can start it. Be sure that all the dashboards you want to appear in your playlist are added when creating or editing the playlist before saving it.
-
-1. To access the Playlist feature, hover your cursor over Grafana's side menu.
-1. Click **Playlists**.
-1. Click on the playlist.
-1. Edit the playlist.
-   - Ensure that your playlist has a **Name**, **Interval**, and at least one **Dashboard** added to it.
-1. Click **Save**.
-
-## Start a playlist
-
-You can start a playlist in five different view modes, which determine how the menus and navigation bar are displayed on the dashboards.
-
-By default, each dashboard is displayed for the amount of time entered in the Interval field, which can be set while creating or editing a playlist. Once a playlist is started, it can be controlled using the navbar at the top of your screen.
-
-1. From the Dashboards submenu, click **Playlists**.
-1. Next to the playlist you want to start, click **Start playlist**.
-1. In the dropdown, select the mode you want the playlist to display in.
-   - **Normal mode:**
-     - The side menu remains visible.
-     - The navbar, row and panel controls appear at the top of the screen.
-   - **TV mode:**
-     - The side menu is hidden/removed.
-     - The navbar, row and panel controls appear at the top of the screen.
-     - Enabled automatically after one minute of user inactivity.
-     - You can enable it manually using the `d v` sequence shortcut, or by appending the parameter `?inactive` to the dashboard URL.
-     - You can disable it with any mouse movement or keyboard action.
-   - **TV mode (with auto fit panels):**
-     - The side menu is hidden/removed.
-     - The navbar, row and panel controls appear at the top of the screen.
-     - Dashboard panels automatically adjust to optimize space on screen.
-   - **Kiosk mode:**
-     - The side menu, navbar, row and panel controls are completely hidden/removed from view.
-     - You can enable it manually using the `d v` sequence shortcut after the playlist has started.
-     - You can disable it manually with the same shortcut.
-   - **Kiosk mode (with auto fit panels):**
-     - The side menu, navbar, row and panel controls are completely hidden/removed from view.
-     - Dashboard panels automatically adjust to optimize space on screen.
-
-## Control a playlist
-
-You can control a playlist in **Normal** or **TV** mode after it's started, using the navigation bar at the top of your screen.
+You can control a playlist in **Normal** or **TV** mode after it's started, using the navigation bar at the top of your screen. Press the Esc key in your keyboard to stop the playlist.
 
 | Button                         | Result                                                                                                                                          |
 | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -132,7 +53,37 @@ You can control a playlist in **Normal** or **TV** mode after it's started, usin
 | Time range                     | Displays data within a time range. It can be set to display the last 5 minutes up to 5 years ago, or a custom time range, using the down arrow. |
 | Refresh (circle arrow)         | Reloads the dashboard, to display the current data. It can be set to reload automatically every 5 seconds to 1 day, using the drop down arrow.  |
 
-> Shortcut: Press the Esc key to stop the playlist from your keyboard.
+## Create a playlist
+
+You can create a playlist to present dashboards in a sequence, with a set order and time interval between dashboards.
+
+1. In the playlist page, click **New playlist**. The New playlist page opens.
+1. In the **Name** text box, enter a descriptive name.
+1. In the **Interval** text bos, enter a time interval. Grafana displays a particular dashboard for the interval of time specified here before moving on to the next dashboard.
+1. In Dashboards, add existing dashboards to the playlist using **Add by title** and **Add by tag** drop-down options. The dashboards you add are listed in a sequential order.
+1. If needed:
+   - Search for a dashboard by its name, a regular expression, or a tag.
+   - Filter your results by starred status or tags.
+1. If needed, rearrange the order of the dashboard you have added using the up and down arrow icon.
+1. Optionally, remove a dashboard from the playlist by clicking the x icon beside dashboard.
+1. Click **Save**.
+
+{{< figure src="/static/img/docs/dashboards/create-playlist-8-2.png" max-width="25rem">}}
+
+## Edit or delete a playlist
+
+You can edit a playlist by updating its name, interval time, and by adding, removing, and rearranging the order of dashboards. On the rare occasion when you no longer need a playlist, you can delete it.
+
+### Edit a playlist
+
+1. In the playlist page, click **Edit playlist**. The Edit playlist page opens.
+1. Update the name and time interval, then add or remove dashboards from the playlist using instructions in [Create a playlist](#create-a-playlist).
+1. Click **Save** to save your changes.
+
+### Delete a playlist
+
+1. In the playlist page, click **Edit playlist**. A prompts opens asking you to confirm the action.
+1. Click **delete**.
 
 ## Share a playlist in a view mode
 
diff --git a/docs/sources/http_api/dashboard.md b/docs/sources/http_api/dashboard.md
index aeb1253af60..a42bd7b1fa7 100644
--- a/docs/sources/http_api/dashboard.md
+++ b/docs/sources/http_api/dashboard.md
@@ -22,7 +22,7 @@ The uid can have a maximum length of 40 characters.
 
 `POST /api/dashboards/db`
 
-Creates a new dashboard or updates an existing dashboard.
+Creates a new dashboard or updates an existing dashboard. When updating existing dashboards, if you do not define the `folderId` or the `folderUid` property, then the dashboard(s) are moved to the General folder. (You need to define only one property, not both).
 
 **Example Request for new dashboard**: