apply suggestions from code review

rchinn1 · rchinn1 · commit c09738fcd6a3 · 2023-09-29T13:10:19.000-07:00
diff --git a/src/connections/storage/databricks-delta-lake/databricks-delta-lake-aws.md b/src/connections/storage/databricks-delta-lake/databricks-delta-lake-aws.md
@@ -4,7 +4,7 @@ beta: true
 ---
 
 With the Databricks Delta Lake Destination, you can ingest event data from Segment into the bronze layer of your Databricks Delta Lake.
-
+ 
 This page will help you use the Databricks Delta Lake Destination to sync Segment events into your Databricks Delta Lake built on S3.
 
 > info "Databricks Delta Lake Destination in Public Beta"
@@ -49,23 +49,25 @@ As you set up Databricks, keep the following key terms in mind.
 ### Step 1: Find your Databricks Workspace URL 
 
 You'll use the Databricks workspace URL, along with Segment, to access your workspace API. 
-- Check your browser's address bar when inside the workspace. The workspace URL will look something like: `https://<workspace-deployment-name>.cloud.databricks.com`. Remove any characters after this portion and note the URL for later use.
+
+Check your browser's address bar when inside the workspace. The workspace URL will look something like: `https://<workspace-deployment-name>.cloud.databricks.com`. Remove any characters after this portion and note the URL for later use.
 
 ### Step 2: Create a service principal 
 
 Segment uses the service principal to access your Databricks workspace and associated APIs.
-1. Follow the Databricks [guide](https://docs.databricks.com/en/administration-guide/users-groups/service-principals.html#manage-service-principals-in-your-account){:target="_blank"} for adding a service principal to your account. This name can be anything, but Segment recommends something that identifies the purpose (for example, "Segment Storage Destinations"). Note the Application ID that Databricks generates for later use. Segment doesn't require Account admin or Marketplace admin roles.
+1. Follow the Databricks guide for [adding a service principal to your account](https://docs.databricks.com/en/administration-guide/users-groups/service-principals.html#manage-service-principals-in-your-account){:target="_blank"}. This name can be anything, but Segment recommends something that identifies the purpose (for example, "Segment Storage Destinations"). Note the Application ID that Databricks generates for later use. Segment doesn't require Account admin or Marketplace admin roles.
 2. (*OAuth only*) Follow the Databricks instructions to [generate an OAuth secret](https://docs.databricks.com/en/dev-tools/authentication-oauth.html#step-2-create-an-oauth-secret-for-a-service-principal){:target="_blank"}. Note the secret generated by Databricks for later use. Once you navigate away from this page, the secret is no longer visible. If you lose or forget the secret, delete the existing secret and create a new one. 
 
 ### Step 3: Enable entitlements for the service principal on the workspace 
 
 This step allows the Segment service principal to create and use a small SQL warehouse, which is used for creating and updating table schemas in the Unity Catalog.
-1. Follow the Databricks [guide](https://docs.databricks.com/en/administration-guide/users-groups/service-principals.html#manage-workspace-entitlements-for-a-service-principal){:target="_blank"} for managing workspace entitlements for a service principal. Segment requires the `Allow cluster creation` and `Databricks SQL access` entitlements.
+
+To enable entitlements for the service principal you just created, follow the Databricks [guide for managing workspace entitlements for a service principal](https://docs.databricks.com/en/administration-guide/users-groups/service-principals.html#manage-workspace-entitlements-for-a-service-principal){:target="_blank"}. Segment requires the `Allow cluster creation` and `Databricks SQL access` entitlements.
 
 ### Step 4: Create an external location and storage credentials 
 
 This step creates the storage location where Segment lands your Delta Lake and the associated credentials Segment uses to access the storage. 
-1. Follow the Databricks guide for [managing external locations and storage credentials](https://docs.databricks.com/en/data-governance/unity-catalog/manage-external-locations-and-credentials.html){:target="_blank"}. This guide assumes the target S3 bucket already exists. If not, follow the [AWS guide](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket-overview.html){:target="_blank"} for creating a bucket.
+1. Follow the Databricks guide for [managing external locations and storage credentials](https://docs.databricks.com/en/data-governance/unity-catalog/manage-external-locations-and-credentials.html){:target="_blank"}. This guide assumes the target S3 bucket already exists. If not, follow the AWS guide for [creating a bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket-overview.html){:target="_blank"}.
 2. Once the external location and storage credentials are created in your Databricks workspace, update the permissions to allow access to the Segment service principal. 
     1. In your workspace, navigate to **Data > External Data > Storage Credentials**. 
     2. Click the name of the credentials created above to go to the Permissions tab. 
@@ -79,8 +81,7 @@ This step creates the storage location where Segment lands your Delta Lake and t
     10. Click **Grant**.
 3. In AWS, supplement the Trust policy for the role created when setting up the storage credentials. 
     1. Add: `arn:aws:iam::595280932656:role/segment-storage-destinations-production-access` to the Principal list.
-    2. Convert the `sts:ExternalID` field to a list and add the Segment Workspace ID.
-    3. You'll find the Segment workspace ID in the Segment app (**Settings > Workspace settings > ID**).
+    2. Convert the `sts:ExternalID` field to a list and add the Segment Workspace ID. You'll find the Segment workspace ID in the Segment app (**Settings > Workspace settings > ID**).
 
 The Trust policy should look like:
 
@@ -115,42 +116,42 @@ The Trust policy should look like:
 ### Step 5: Create a workspace admin access token (PAT only) 
 
 Your Databricks workspace admin uses the workspace admin access token to generate a personal access token for the service principal. 
-1. Follow the Databricks guide for [generating personal access tokens](https://docs.databricks.com/en/dev-tools/auth.html#databricks-personal-access-tokens-for-workspace-users){:target="_blank"} for workspace users. Note the generated token for later use.
+
+To create your token, follow the Databricks guide for [generating personal access tokens](https://docs.databricks.com/en/dev-tools/auth.html#databricks-personal-access-tokens-for-workspace-users){:target="_blank"} for workspace users. Note the generated token for later use.
 
 ### Step 6: Enable personal access tokens for the workspace (PAT only) 
 
 This step allows the creation and use of personal access tokens for the workspace admin and the service principal.
-1. Follow the Databricks [guide](https://docs.databricks.com/en/administration-guide/access-control/tokens.html#enable-or-disable-personal-access-token-authentication-for-the-workspace){:target="_blank"} for enabling personal access token authentication for the workspace. 
+1. Follow the Databricks guide for [enabling personal access token authentication](https://docs.databricks.com/en/administration-guide/access-control/tokens.html#enable-or-disable-personal-access-token-authentication-for-the-workspace){:target="_blank"} for the workspace. 
 2. Follow the Databricks docs to [grant Can Use permission](https://docs.databricks.com/en/security/auth-authz/api-access-permissions.html#manage-token-permissions-using-the-admin-settings-page){:target="_blank"} to the Segment service principal created earlier. 
 
 ### Step 7: Generate a personal access token for the service principal (PAT only) 
 
 Segment uses the personal access token to access the Databricks workspace API. The Databricks UI doesn't allow for the creation of service principal tokens. Tokens must be generated using either the Databricks workspace API (*recommended*) or the Databricks CLI. 
-1. Generating a token requires the following values:
+Generating a token requires the following values:
 - **Databricks Workspace URL**: The base URL to your Databricks workspace. 
 - **Workspace Admin Token**: The token generated for your Databricks admin user.
 - **Service Principal Application ID**: The ID generated for the Segment service principal. 
 - **Lifetime Seconds**: The number of seconds before the token expires. Segment doesn't prescribe a specific token lifetime. Using the instructions below, you'll need to generate and update a new token in the Segment app before the existing token expires. Segment's general guidance is 90 days (7776000 seconds). 
 - **Comment**: A comment which describes the purpose of the token (for example, "Grants Segment access to this workspace until 12/21/2023"). 
-2. (*Recommended option*) To create the token with the API, execute the following command in a terminal or command line tool. Be sure to update the placeholders with the relevant details from above. For more information about the API check out the [Databricks API docs](https://docs.databricks.com/api/workspace/tokenmanagement/createobotoken){:target="_blank"}.
+1. (*Recommended option*) To create the token with the API, execute the following command in a terminal or command line tool. Be sure to update the placeholders with the relevant details from above. For more information about the API check out the [Databricks API docs](https://docs.databricks.com/api/workspace/tokenmanagement/createobotoken){:target="_blank"}.
 ```
 curl --location 
 '<DATABRICKS_WORKSPACE_URL>/api/2.0/token-management/on-behalf-of/tokens' --header 'Content-Type: application/json' --header 'Authorization: Bearer <WORKSPACE_ADMIN_TOKEN>' --data '{"application_id": "<SERVICE_PRINCIPAL_APPLICATION_ID>", "lifetime_seconds": <LIFETIME_SECONDS>, "comment": "<COMMENT>"}'
 ```
-- The response from the API contains a `token_value` field. Note this value for later use. 
-3. (*Alternative option*) If you prefer to use the Databricks CLI, execute the following command in a terminal or command line tool. Be sure to update the placeholders with the relevant details from above. You will also need to [set up a profile](https://docs.databricks.com/en/dev-tools/cli/databricks-cli-ref.html#databricks-personal-access-token-authentication){:target="_blank"} for the CLI. For more info, check out the [Databricks CLI docs](https://docs.databricks.com/en/dev-tools/cli/databricks-cli-ref.html){:target="_blank"}.
+The response from the API contains a `token_value` field. Note this value for later use. 
+2. (*Alternative option*) If you prefer to use the Databricks CLI, execute the following command in a terminal or command line tool. Be sure to update the placeholders with the relevant details from above. You will also need to [set up a profile](https://docs.databricks.com/en/dev-tools/cli/databricks-cli-ref.html#databricks-personal-access-token-authentication){:target="_blank"} for the CLI. For more info, check out the [Databricks CLI docs](https://docs.databricks.com/en/dev-tools/cli/databricks-cli-ref.html){:target="_blank"}.
 
-``` 
-databricks token-management create-obo-token 
-<SERVICE_PRINCIPAL_APPLICATION_ID> <LIFETIME_SECONDS> --comment <COMMENT> -p <PROFILE_NAME>
-```
-- The response from the CLI will contain a `token_value` field. Note this value for later use. 
+    ``` 
+    databricks token-management create-obo-token 
+    <SERVICE_PRINCIPAL_APPLICATION_ID> <LIFETIME_SECONDS> --comment <COMMENT> -p <PROFILE_NAME>
+    ```
+The response from the CLI will contain a `token_value` field. Note this value for later use. 
 
 ### Step 8: Create a new catalog in Unity Catalog and grant Segment permissions 
 
 This catalog is the target catalog where Segment lands your schemas/tables. 
-1. Follow the Databricks guide for [creating a catalog](https://docs.databricks.com/en/data-governance/unity-catalog/create-catalogs.html#create-a-catalog){:target="_blank"}. 
-- Be sure to select the storage location created earlier. You can use any valid catalog name (for example, "Segment"). Note this name for later use. 
+1. Follow the Databricks guide for [creating a catalog](https://docs.databricks.com/en/data-governance/unity-catalog/create-catalogs.html#create-a-catalog){:target="_blank"}. Be sure to select the storage location created earlier. You can use any valid catalog name (for example, "Segment"). Note this name for later use. 
 2. Select the catalog you've just created. 
     1. Select the Permissions tab, then click **Grant** 
     2. Select the Segment service principal from the dropdown, and check `ALL PRIVILEGES`.
diff --git a/src/connections/storage/databricks-delta-lake/databricks-delta-lake-azure.md b/src/connections/storage/databricks-delta-lake/databricks-delta-lake-azure.md
@@ -7,7 +7,7 @@ With the Databricks Delta Lake Destination, you can ingest event data from Segme
 
 This page will help you use the Databricks Delta Lake Destination to sync Segment events into your Databricks Delta Lake built on Azure (ADLS Gen 2).
 
-
+ 
 > info "Databricks Delta Lake Destination in Public Beta"
 > The Databricks Delta Lake Destination is in public beta, and Segment is actively working on this integration. [Contact Segment](https://segment.com/help/contact/){:target="_blank"} with any feedback or questions.
 
@@ -56,17 +56,17 @@ Segment uses the service principal to access your Databricks workspace APIs as w
     2. Open a Cloud Shell (first button to the right of the top search bar).
     3. Once loaded, enter the following command in the shell:
 
-```
-New-AzADServicePrincipal -applicationId fffa5b05-1da5-4599-8360-cc2684bcdefb
-```
+    ```
+    New-AzADServicePrincipal -applicationId fffa5b05-1da5-4599-8360-cc2684bcdefb
+    ```
 
 2. **(Alternative option)** Azure CLI
     1. Log into the Azure CLI using the [az login command](https://learn.microsoft.com/en-us/cli/azure/authenticate-azure-cli){:target="_blank"}.
     2. Once authenticated, run the following command:
 
-```
-az ad sp create --id fffa5b05-1da5-4599-8360-cc2684bcdefb
-```
+    ```
+    az ad sp create --id fffa5b05-1da5-4599-8360-cc2684bcdefb
+    ```
 
 ### Step 3: Update or create an ADLS Gen2 storage container 
 
@@ -82,10 +82,10 @@ The ADLS Gen2 storage container is where Segment lands your Delta Lake files.
 8. Click **+ Select members**, then search for and select "Segment Storage Destinations".
 9. Click **Review + assign**.
 
-### Step 4: Add the Segment Storage Destinations service pricipal to the account/workspace 
+### Step 4: Add the Segment Storage Destinations service principal to the account/workspace 
 
 This step allows Segment to access your workspace. 
-1. Follow the Databricks [guide](https://learn.microsoft.com/en-us/azure/databricks/administration-guide/users-groups/service-principals#add-service-principals-to-your-account-using-the-account-console){:target="_blank"} for adding a service principal using the account console. 
+1. Follow the Databricks guide for [adding a service principal](https://learn.microsoft.com/en-us/azure/databricks/administration-guide/users-groups/service-principals#add-service-principals-to-your-account-using-the-account-console){:target="_blank"} using the account console. 
 - Segment recommends using "Segment Storage Destinations" for the name, though any identifier is allowed. 
 - For the **UUID** enter `fffa5b05-1da5-4599-8360-cc2684bcdefb`.
 - Segment doesn't require Account admin access.
@@ -97,16 +97,16 @@ This step allows Segment to access your workspace.
 
 This step allows the Segment service principal to create a small SQL warehouse for creating and updating table schemas in the Unity Catalog.
 
-1. Follow the [managing workspace entitlements](https://learn.microsoft.com/en-us/azure/databricks/administration-guide/users-groups/service-principals#--manage-workspace-entitlements-for-a-service-principal){:target="_blank"} instructions for a service principal. Segment requires `Allow cluster creation` and `Databricks SQL access` entitlements.
+To enable entitlements, follow the [managing workspace entitlements](https://learn.microsoft.com/en-us/azure/databricks/administration-guide/users-groups/service-principals#--manage-workspace-entitlements-for-a-service-principal){:target="_blank"} instructions for a service principal. Segment requires `Allow cluster creation` and `Databricks SQL access` entitlements.
 
 ### Step 6: Create an external location and storage credentials 
 
 This step creates the storage location where Segment lands your Delta Lake and the associated credentials Segment uses to access the storage. 
 1. Follow the Databricks guide for [managing external locations and storage credentials](https://learn.microsoft.com/en-us/azure/databricks/data-governance/unity-catalog/manage-external-locations-and-credentials){:target="_blank"}. 
 - Use the storage container you updated in step 3.
 - For storage credentials, you can use a service principal or managed identity.
-2. Once you create the external location and storage credentials in your Databricks workspace, update the permissions to allow access to the Segment service principal. 
-- In your workspace, navigate to **Data > External Data > Storage Credientials**. Click the name of the credentials created above and go to the Permissions tab. Click **Grant**, then select the Segment service principal from the drop down. Select the following checkboxes:
+2. Once you create the external location and storage credentials in your Databricks workspace, update the permissions to allow access to the Segment service principal. <br><br>
+In your workspace, navigate to **Data > External Data > Storage Credentials**. Click the name of the credentials created above and go to the Permissions tab. Click **Grant**, then select the Segment service principal from the drop down. Select the following checkboxes:
 - `CREATE EXTERNAL TABLE`
 - `READ FILES`
 - `WRITE FILES`
