Doc updates (Netflix#617)

Author: patcable

docs/configuration/app.md

@@ -157,7 +157,8 @@ Dispatch [calculates](https://github.com/Netflix/dispatch/blob/develop/src/dispa
 
 #### `INCIDENT_STORAGE_FOLDER_ID`
 
-> Top level folder where all incident data is stored. Note: viewing actual incident data is still on a per-sub folder basis.
+> Top level folder where all incident data is stored. Note: viewing actual incident data is still on a per-sub folder basis. For Google Drive,
+> you can get the folder ID from viewing a folder in the Google Drive UI, and copying the last part of the URL (`/drive/u/0/folders/<this value>`)
 
 #### `INCIDENT_STORAGE_OPEN_ON_CLOSE` \[default: 'true'\]
 

docs/configuration/plugins/configuring-g-suite.md

@@ -2,12 +2,15 @@
 description: Configuration page for all G Suite plugins.
 ---
 
-# Configuring G Suite
+# Configuring G Suite Integration
 
 {% hint style="info" %}
-Dispatch ships with several G Suite plugins \(Docs, Groups, Drive, etc.,\). This page documents the available configuration for these plugins and the permissions required to enable them. These plugins are required for core functionality.
+Dispatch ships with several G Suite plugins \(Docs, Groups, Drive, etc.,\). This page documents the available configuration
+for these plugins and the permissions required to enable them. These plugins are required for core functionality.
 {% endhint %}
 
+## Dispatch Configuration Variables
+
 ### `GOOGLE_DOMAIN` \[Required\]
 
 > Base domain for which this Google Cloud Platform \(GCP\) service account resides.
@@ -18,49 +21,55 @@ Dispatch ships with several G Suite plugins \(Docs, Groups, Drive, etc.,\). This
 
 ### `GOOGLE_SERVICE_ACCOUNT_CLIENT_EMAIL` \[Required\]
 
-> Client email for the Google Cloud Platform \(GCP\) service account.
+> The `client_email` value from your Google Cloud Platform \(GCP\) service account configuration file.
 
 ### `GOOGLE_SERVICE_ACCOUNT_CLIENT_ID` \[Required\]
 
-> Client ID for the Google Cloud Platform \(GCP\) service account.
+> The `client_id` value from your Google Cloud Platform \(GCP\) service account configuration file.
 
 ### `GOOGLE_SERVICE_ACCOUNT_DELEGATED_ACCOUNT` \[Required\]
 
 > Account to delegate to from the Google Cloud Platform \(GCP\) service account.
+> Outgoing emails and other artifacts will appear to be from this account.
 
 ### `GOOGLE_SERVICE_ACCOUNT_PRIVATE_KEY` \[Required. Secret: True\]
 
-> Private key \(PEM format\) for the Google Cloud Platform \(GCP\) service account.
+> The `private_key` value from your Google Cloud Platform \(GCP\) service account configuration file.
 
 ### `GOOGLE_SERVICE_ACCOUNT_PRIVATE_KEY_ID` \[Required\]
 
-> Private key ID for the Google Cloud Platform \(GCP\) service account.
+> The `private_key_id` value from your Google Cloud Platform \(GCP\) service account configuration file.
 
 ### `GOOGLE_SERVICE_ACCOUNT_PROJECT_ID` \[Required\]
 
-> Project ID for the Google Cloud Platform \(GCP\) service account.
+> The `project_id` value from your Google Cloud Platform \(GCP\) service account configuration file.
 
 ### `GOOGLE_USER_OVERRIDE` \[Optional. Default: None\]
 
 > Used for development to funnel all emails to a specific user.
 
-## Enable Required APIs
+## G Suite Setup
+
+To set up G Suite integration, you'll need to create some resources in Google Cloud Platform, and then link them to your
+G Suite organization.
 
-This is meant to provide guidance on enabling Dispatch's G Suite plugins, your organization may differ slightly.
+## Enable Required APIs in Google Cloud Platform
 
-Navigate to the Google Cloud Platform \(GCP\) [console](https://console.cloud.google.com/).
+Navigate to the Google Cloud Platform \(GCP\) [console](https://console.cloud.google.com/). You will want to
+create a new GCP Project for Dispatch's integration.
 
-Create a new service account \(APIs & Services > Credentials > Create Credentials > Service Account\).
+Create a new service account within the GCP project \(APIs & Services > Credentials > Create Credentials > Service Account\). 
+You do not need to assign any Google Cloud permissions to this service account when prompted.
 
-Once created, download the JSON based key and use it's values to populate the above configuration values:
+Once created, download the JSON based key. You'll use these values to configure Dispatch:
 
 * `project_id` -> `GOOGLE_SERVICE_ACCOUNT_PROJECT_ID`
-* `private_key_id` -> `GOOGLE_SERVICE_PRIVATE_KEY_ID`
-* `private_key` -> `GOOGLE_SERVICE_PRIVATE_KEY`
+* `private_key_id` -> `GOOGLE_SERVICE_ACCOUNT_PRIVATE_KEY_ID`
+* `private_key` -> `GOOGLE_SERVICE_ACCOUNT_PRIVATE_KEY`
 * `client_email` -> `GOOGLE_SERVICE_ACCOUNT_CLIENT_EMAIL`
 * `client_id` -> `GOOGLE_SERVICE_ACCOUNT_CLIENT_ID`
 
-Create a Developer API key \(APIs & Services > Credentials > Create Credentials > API Key\), and set the value of `GOOGLE_DEVELOPER_KEY`.
+Then, create a Developer API key \(APIs & Services > Credentials > Create Credentials > API Key\), and set it to the value for `GOOGLE_DEVELOPER_KEY`.
 
 Enable the following APIs \(APIs and Services > Library\):
 
@@ -70,18 +79,8 @@ Enable the following APIs \(APIs and Services > Library\):
 * Gmail API
 * Admin SDK \(necessary to create and manage groups\)
 
-{% hint style="info" %}
-If you are planning on using Google Drive storage you must enable the folder sharing beta.
-
-[https://support.google.com/a/answer/9890318?hl=en\#:~:text=Help%20CenterCommunity-,Folder%20sharing%20in%20shared%20drives%20\(beta\),folders%20within%20a%20shared%20drive](https://support.google.com/a/answer/9890318?hl=en#:~:text=Help%20CenterCommunity-,Folder%20sharing%20in%20shared%20drives%20%28beta%29,folders%20within%20a%20shared%20drive)
-
-To signup:  
-[https://docs.google.com/forms/d/e/1FAIpQLSfrILe0\_bPkkI7pxfr-4rHk0qcajrUOHTcmrWPOVLo0SKNF7A/viewform](https://docs.google.com/forms/d/e/1FAIpQLSfrILe0_bPkkI7pxfr-4rHk0qcajrUOHTcmrWPOVLo0SKNF7A/viewform)
-{% endhint %}
-
-Finally, map the `client_id` of the created service with the required OAuth2 scopes.
-
-Navigate to admin [home](https://admin.google.com/AdminHome?chromeless=1#OGX:ManageOauthClients%20) \(Security > Advanced Settings > Manage API Client Access\), and add the following scopes:
+Finally, create your OAuth application which is how G Suite will authorize the service account and API key \(APIs & Services > OAuth Consent Screen\).
+Specify the following scopes:
 
 ```text
 https://www.googleapis.com/auth/documents
@@ -94,10 +93,9 @@ https://www.googleapis.com/auth/calendar
 
 **Note:** If you will not use Google Meet for your conference then you do not need the `https://www.googleapis.com/auth/calendar` scope.
 
-Then construct this link and click it:
+## Connecting Dispatch to G Suite
 
-```text
-https://admin.google.com/AdminHome?clientScopeToAdd=https://www.googleapis.com/auth/documents,https://www.googleapis.com/auth/drive,https://mail.google.com/,https://www.googleapis.com/auth/admin.directory.group,https://www.googleapis.com/auth/apps.groups.settings,https://www.googleapis.com/auth/calendar
-&clientNameToAdd=<INSERTCLIENTIDHERE>&chromeless=1#OGX:ManageOauthClients
-```
+Navigate to the G Suite Admin [Domain-wide Delegation](https://admin.google.com/ac/owl/domainwidedelegation) page 
+\(Security &gt; API Controls &gt; Domain-wide Delegation\) and add a new API client. 
 
+Enter the Client ID you used for `GOOGLE_SERVICE_ACCOUNT_CLIENT_ID`, and then paste in a comma-separated list of the OAuth scopes above.

docs/user-guide/administration/knowledge.md

@@ -24,7 +24,7 @@ To create a new tag navigate to: `Dispatch > Tags > New`
 
 **URI:** The external tag locator (if available).
 
-**Discoverable:** Dispatch has the ability to do some automatic tag discovery. Meaning given a set of predefined tags, it will crawl all incident data available to it and using NLP associate this data to incidents (current incident and retroactively). If for some reason a tag is general enough (e.g. "the") that you do not want to make it disoverable, this flag can disable that functionality on an individual tag basis.
+**Discoverable:** Dispatch has the ability to do some automatic tag discovery. Meaning given a set of predefined tags, it will crawl all incident data available to it and using NLP associate this data to incidents (current incident and retroactively). If for some reason a tag is general enough (e.g. "the") that you do not want to make it discoverable, this flag can disable that functionality on an individual tag basis.
 
 ## Documents
 
@@ -34,6 +34,8 @@ To create a new document navigate to: `Dispatch > Documents > New`
 
 Documents are links to external sources \(Web Pages, Google Documents, etc.,\). These documents can be associated with terms, incident types, and incident priorities, allowing these documents to be recommended reading for incident participants.
 
+If you use the Google Drive plugin, Dispatch will copy a Google document associated with an incident type into a folder. Make sure you specify the correct Google Docs ID for the `ID` field.
+
 **Name:** Name of the document.
 
 **Description:** Short description of the document.
@@ -52,7 +54,7 @@ In addition to fields about the document itself, Dispatch allows you to associat
 
 Documents can also be used as templates during incident creation that Dispatch will attempt to fill when copied.
 
-If you are using the google drive plugin, we provide a set of templates to get you started, these should be copied into your google drive and then created as documents in the Dispatch UI.
+If you are using the Google Drive plugin, we provide a set of templates to get you started, these should be copied into your Google Drive and then created as documents in the Dispatch UI.
 
 - [Incident Document](https://docs.google.com/document/d/1fv--CrGpWJJ4nyPR0N0hq4JchHJPuqsXN4azE9CGQiE)