Merge pull request juju#1243 from matthewhelmke/azureupdate

rephrased in places for enhanced clarity

Author: matthewhelmke

src/en/help-azure.md

@@ -38,15 +38,18 @@ sudo npm install -g azure-cli
 The Azure CLI tool gets installed here:
 
 ```bash
-ls -lh /usr/bin/azure
-lrwxrwxrwx 1 root root 39 Jan 18 22:58 /usr/bin/azure -> ../lib/node_modules/azure-cli/bin/azure
+ls -lh /usr/local/bin/azure
+lrwxrwxrwx 1 root root 39 Jan 18 22:58 /usr/local/bin/azure -> ../lib/node_modules/azure-cli/bin/azure
 ```
 
-Confirm it's installed correctly by viewing its online help. Then put it in
-*Azure Resource Manager* mode and log in:
+Confirm the tool is installed correctly by viewing its online help.
 
 ```bash
 azure help
+```
+
+Put Azure in *Azure Resource Manager* mode and log in:
+```bash
 azure config mode arm
 azure login
 ```
@@ -56,8 +59,8 @@ therefore be easier to perform this on a graphical desktop.
 
 ### Registering azure services
 
-Juju requires certain services to be active for your account. This can 
-be done with the Azure CLI tool:
+Juju requires certain services to be active for your account. Enter these 
+commands to register using the Azure CLI tool:
 
 ```
 azure provider register Microsoft.Compute
@@ -72,15 +75,19 @@ To enter credentials, values will need to be found for the following parameters:
  - application-id
  - tenant-id
 
+!!! Note: In the sections below, we will assign each of these a variable name.
+When you enter them into the command, replace the variable name we give with
+the actual ID that corresponds to the variable.
+
 ### `subscription-id`
 
-List your account and get the subscription ID, the **SUB_ID**:
+List your account. Note the subscription ID, the **SUB_ID**.
 
 ```bash
 azure account list
 ```
 
-Sample output:
+**SUB_ID** will appear on a line like this:
 
 ```no-highlight
 info:    Executing command account list
@@ -90,24 +97,22 @@ data:    Free Trial  f717c8c1-8e5e-4d38-be7f-ed1e1c879e18  true     Enabled
 info:    account list command OK
 ```
 
-The subscription ID can now be stored in a local environment variable, by
-entering:
+In the output of this command, the **SUB_ID** is not labeled as such. In our
+sample it was next to last line, so:
 
 ```bash
 SUB_ID=f717c8c1-8e5e-4d38-be7f-ed1e1c879e18
 ```
 
-### `application-password`
+### `application-password` and  `application-id`
 
-You will create an application in the next step. For now, create a password for
-it, the **APP_PASSWORD**.
+Create a password for the application to use, the **APP_PASSWORD**. In our
+sample,
 
 ```bash
 APP_PASSWORD=some_password
 ```
 
-### `application-id`
-
 Create an Azure Active Directory (AAD) application:
 
 ```bash
@@ -121,22 +126,26 @@ azure ad app create \
 The options `--name`, `--home-page`, and `--identifier-uris` are arbitrary but
 you should use values that make sense for your environment.
 
-Note the application ID, the **APP_ID**. It will look similar to:
+In the output of this command, note the application ID, the **APP_ID**.
+In our sample it was on a line like this:
 
 ```bash
-APP_ID=f6ab7cbd-5029-43ef-85e3-5c4442a00ba8
+data:    AppId:    f6ab7cbd-5029-43ef-85e3-5c4442a00ba8
 ```
 
 Use the APP_ID to create an Active Directory (Kerberos) server principal:
 
+!!! Note: Replace our variable here with the actual value you learned above.
+Do this throughout the rest of this page when you see variables listed.
+
 ```bash
 azure ad sp create -a $APP_ID
 ```
 
-Note its object ID, the **OBJ_ID**:
+Note its object ID, the **OBJ_ID**. In our sample it was on a line like this:
 
 ```bash
-OBJ_ID=aab17f6f-6b9a-43ae-8d6d-2ff889aa8941
+data:    ObjectId:    aab17f6f-6b9a-43ae-8d6d-2ff889aa8941
 ```
 
 Now grant permissions to the principal (OBJ_ID) associated with your
@@ -157,10 +166,10 @@ Get the tenant id, the **TENANT_ID**:
 azure account show
 ```
 
-It will look like:
+In our sample it was on a line like this:
 
 ```bash
-TENANT_ID=daff614b-725e-4b9a-bc57-7763017c1cfb
+data:    Tenant ID:    daff614b-725e-4b9a-bc57-7763017c1cfb
 ```
 
 You can test by logging in using the application principal as your identity:
@@ -179,12 +188,21 @@ You can now run the interactive command:
 juju add-credential azure
 ```
 
-Which will ask for a credential name, and then the values discovered above.
+Which will ask for an arbitrary credential name, which you choose for yourself.
+This will be how you remember and refer to this Azure credential in Juju. The
+command will also request the values discovered above, which we referred to as:
+
+```bash
+APP_ID
+SUB_ID
+TENANT_ID
+APP_PASSWORD
+```
 
 !!! Note: If you add more than one credential, you will also need to set the
 default one to use with `juju set-default-credential`
 
-## Bootstrap
+## Create controller
 
 
 ```bash