Update Spotify documentation including playlists (home-assistant#15462)

lindsaymarkward · web-flow · commit 358c1ee14d06 · 2020-10-31T20:52:49.000+01:00
* Update Spotify documentation including playlists

Improve English language use for readability; add example of play_media with Spotify playlist; add note about playlists not working on Google Nest Home devices.

* Improve Spotify documentation after feedback

Remove note about Google Home not working, fix code block
diff --git a/source/_integrations/spotify.markdown b/source/_integrations/spotify.markdown
@@ -20,17 +20,17 @@ The Spotify media player integration allows you to control [Spotify](https://www
 - Spotify application configured for Home Assistant (see [below](#create-a-spotify-application))
 
 <div class='note'>
-  Spotify integrated media controls (pause, play, next, etc.) requires a Premium account.
-  If you do not have a Premium account, the integration's frontend will not show the controls.
+  Spotify integrated media controls (pause, play, next, etc.) require a Premium account.
+  If you do not have a Premium account, the frontend will not show the controls.
 </div>
 
 ### Create a Spotify application
 
 - Login to [Spotify Developer](https://developer.spotify.com).
 - Visit the [My Applications](https://developer.spotify.com/my-applications/#!/applications) page.
 - Select **Create An App**. Enter any name and description.
-- Once your application is created, view it and copy your **Client ID** and **Client Secret**, which are used in the Home Assistant configuration file.
-- On the Spotify page, enter the **Edit Settings** dialog of your newly created application and add a *Redirect URI*:
+- Once your application is created, view it and copy your **Client ID** and **Client Secret**, which are used in the Home Assistant [configuration file below](#configuration).
+- Enter the **Edit Settings** dialog of your newly-created application and add a *Redirect URI*:
   - If you are not using SSL: `http://<your_home_assistant_url_or_local_ip>:<port>/auth/external/callback`
   - If you are using SSL: `https://<your_home_assistant_url_or_local_ip>:<port>/auth/external/callback`
 - Click **Save** after adding the URI.
@@ -52,18 +52,18 @@ spotify:
 
 {% configuration %}
 client_id:
-  description: Client ID from your Spotify application.
+  description: Client ID from your Spotify Developer application.
   required: true
   type: string
 client_secret:
-  description: Client Secret from your Spotify application.
+  description: Client Secret from your Spotify Developer application.
   required: true
   type: string
 {% endconfiguration %}
 
 ## Activating the Spotify integration
 
-- Go to the **Configurations** page in the Home Assistant frontend.
+- Go to the **Configuration** page in the Home Assistant frontend.
 - Click on **Integrations**.
 - Click the orange **+** on the bottom-right.
 - Click on "Spotify".
@@ -72,29 +72,40 @@ client_secret:
 <div class='note'>
 
   If you receive an `INVALID_CLIENT: Invalid redirect URI` error while trying to
-  authenticate with your Spotify account, make sure to check the Redirect URI in
+  authenticate with your Spotify account, check the Redirect URI in
   the address bar after adding the new integration. Compare this value with the
   Redirect URI defined in the Spotify Developer Portal.
 
 </div>
 
 ## Using multiple Spotify accounts
 
-The integration support multiple Spotify accounts at once. You don't need to
+This integration supports multiple Spotify accounts at once. You don't need to
 create another Spotify application in the Spotify Developer Portal and no
 modification to the `configuration.yaml` file is needed. Multiple Spotify
 accounts can be linked to a _single_ Spotify application.
 
-To add an additional Spotify account to Home Assistant, repeat _only_ the steps
-in the [Activating the Spotify integration](#activating-the-spotify-integration)
-section. However, make sure you go to the Spotify website and log out before
-you do so.
+To add an additional Spotify account to Home Assistant, go to the Spotify website and log out, then repeat _only_ the steps
+in the [Activating the Spotify integration](#activating-the-spotify-integration) section. 
 
-## URI Links for Playlists
+## Playing Spotify playlists
 
 You can send playlists to Spotify using the `"media_content_type": "playlist"`, which is part of the
-[media_player.play_media](/integrations/media_player/#service-media_playerplay_media) service.
-The `media_content_id` can be obtained from the Spotify desktop-app by clicking on the more options ("...") next to the album art picture, selecting "share" and then "Copy Spotify URI" or "Copy Playlist Link" (also available in the Spotify phone and web app).
+[media_player.play_media](/integrations/media_player/#service-media_playerplay_media) service, for example:
+
+```yaml
+# Example script to play playlist
+script:
+  play_jazz_guitar:
+    sequence:
+      - service: media_player.play_media
+        data:
+          entity_id: media_player.spotify
+          media_content_id: 'https://open.spotify.com/playlist/5xddIVAtLrZKtt4YGLM1SQ?si=YcvRqaKNTxOi043Qn4LYkg'
+          media_content_type: playlist
+```
+
+The `media_content_id` value can be obtained from the Spotify desktop app by clicking on the more options ("...") next to the album art picture, selecting "Share" and then "Copy Spotify URI" or "Copy Playlist Link" (also available in the Spotify phone and web app).
 
 ## Unsupported Devices
 
