Clarify and cross link installation docs

Author: kgremban

articles/iot-edge/how-to-install-iot-edge-linux-arm.md

@@ -1,21 +1,23 @@
 ---
-title: How to install Azure IoT Edge on Linux | Microsoft Docs
-description: Azure IoT Edge installation instructions on Linux on ARM32
+title: Install Azure IoT Edge on Linux ARM32 | Microsoft Docs
+description: Azure IoT Edge installation instructions on Linux on ARM32 devices, like a Raspberry PI
 author: kgremban
 manager: timlt
 # this is the PM responsible
 ms.reviewer: veyalla
 ms.service: iot-edge
 services: iot-edge
 ms.topic: conceptual
-ms.date: 08/14/2018
+ms.date: 08/27/2018
 ms.author: kgremban
 ---
 # Install Azure IoT Edge runtime on Linux (ARM32v7/armhf)
 
-The Azure IoT Edge runtime is deployed on all IoT Edge devices. It has three components. The **IoT Edge security daemon** provides and maintains security standards on the Edge device. The daemon starts on every boot and bootstraps the device by starting the IoT Edge agent. The **IoT Edge agent** facilitates deployment and monitoring of modules on the Edge device, including the IoT Edge hub. The **IoT Edge hub** manages communications between modules on the IoT Edge device, and between the device and IoT Hub.
+The Azure IoT Edge runtime is what turns a device into an IoT Edge device. The runtime can be deployed on devices as small as Raspberry Pis or as large as industrial servers. Once a device is configured with the IoT Edge runtime, it can start receiving code deployments from the cloud. 
 
-This article lists the steps to install the Azure IoT Edge runtime on a Linux ARM32v7/armhf Edge device (for example, Raspberry Pi).
+To learn more about how the IoT Edge runtime works and what components are included, see [Understand the Azure IoT Edge runtime and its architecture](iot-edge-runtime.md).
+
+This article lists the steps to install the Azure IoT Edge runtime on a Linux ARM32v7/armhf Edge device. For example, these steps would work for Raspberry Pi devices. Refer to [Azure IoT Edge support](support.md#operating-systems) for a list of ARM32 operating systems that are currently supported. 
 
 >[!NOTE]
 >Packages in the Linux software repositories are subject to the license terms located in each package (/usr/share/doc/*package-name*). Read the license terms prior to using the package. Your installation and use of the package constitutes your acceptance of these terms. If you do not agree with the license terms, do not use the package.
@@ -26,7 +28,7 @@ Azure IoT Edge relies on an [OCI-compatible][lnk-oci] container runtime. For pro
 
 Commands below install both the Moby-based engine and command-line interface (CLI). The CLI is useful for development but optional for production deployments.
 
-```cmd/sh
+```bash
 
 # You can copy the entire text from this code block and 
 # paste in terminal. The comment lines will be ignored.
@@ -44,7 +46,10 @@ sudo apt-get install -f
 
 ## Install the IoT Edge Security Daemon
 
-```cmd/sh
+The **IoT Edge security daemon** provides and maintains security standards on the Edge device. The daemon starts on every boot and bootstraps the device by starting the rest of the IoT Edge runtime. 
+
+
+```bash
 # You can copy the entire text from this code block and 
 # paste in terminal. The comment lines will be ignored.
 
@@ -58,18 +63,26 @@ curl -L https://aka.ms/iotedged-linux-armhf-latest -o iotedge.deb && sudo dpkg -
 sudo apt-get install -f
 ```
 
-## Configure the Azure IoT Edge Security Daemon
+## Connect your device to an IoT hub 
 
+Configure the IoT Edge runtime to link your physical device with a device identity that exists in an Azure IoT hub. 
 
 The daemon can be configured using the configuration file at `/etc/iotedge/config.yaml`. The file is write-protected by default, you might need elevated permissions to edit it.
 
+A single IoT Edge device can be provisioned manually using a device connections string provided by IoT Hub. Or, you can use the Device Provisioning Service to automatically provision devices, which is helpful when you have many devices to provision. Depending on your provisioning choice, choose the appropriate installation script. 
+
+### Option 1: Manual provisioning
+
+To manually provision a device, you need to provide it with a [device connection string][lnk-dcs] that you can create by registering a new device in your IoT hub.
+
+
+Open the configuration file. 
+
 ```bash
 sudo nano /etc/iotedge/config.yaml
 ```
 
-The edge device can be configured manually using a [device connection string][lnk-dcs] or [automatically via Device Provisioning Service][lnk-dps].
-
-* For manual configuration, uncomment the **manual** provisioning mode. Update the value of **device_connection_string** with the connection string from your IoT Edge device.
+Find the provisioning section of the file and uncomment the **manual** provisioning mode. Update the value of **device_connection_string** with the connection string from your IoT Edge device.
 
    ```yaml
    provisioning:
@@ -83,7 +96,27 @@ The edge device can be configured manually using a [device connection string][ln
    #   registration_id: "{registration_id}"
    ```
 
-* For automatic configuration, uncomment the **dps** provisioning mode. Update the values of **scope_id** and **registration_id** with the values from your IoT Hub DPS instance and your IoT Edge device with TPM. 
+Save and close the file. 
+
+   `CTRL + X`, `Y`, `Enter`
+
+After entering the provisioning information in the configuration, restart the daemon:
+
+```bash
+sudo systemctl restart iotedge
+```
+
+### Option 2: Automatic provisioning
+
+To automatically provision a device, [set up Device Provisioning Service and retrieve your device registration ID][lnk-dps] (DPS). Automatic provisioning only works with devices that have a Trusted Platform Module (TPM) chip. For example, Raspberry Pi devices do not come with TPM by default. 
+
+Open the configuration file. 
+
+```bash
+sudo nano /etc/iotedge/config.yaml
+```
+
+Find the provisioning section of the file and uncomment the **dps** provisioning mode. Update the values of **scope_id** and **registration_id** with the values from your IoT Hub Device Provisioning Service and your IoT Edge device with TPM. 
 
    ```yaml
    # provisioning:
@@ -103,12 +136,10 @@ Save and close the file.
 
 After entering the provisioning information in the configuration, restart the daemon:
 
-```cmd/sh
+```bash
 sudo systemctl restart iotedge
 ```
 
->[!TIP]
->You need elevated privileges to run `iotedge` commands. Once you sign out of your machine and sign back in the first time after installing the IoT Edge runtime, your permissions are automatically updated. Until then, use **sudo** in front of the commands. 
 
 ## Verify successful installation
 
@@ -131,13 +162,17 @@ And, list running modules with:
 ```cmd/sh
 sudo iotedge list
 ```
->[!NOTE]
->On resource constrained devices like RaspberryPi, it is highly recommended that *OptimizeForPerformance* environment variable is set to *false* as per instructions in the [troubleshooting guide.][lnk-trouble]
 
 
+## Tips and suggestions
+
+You need elevated privileges to run `iotedge` commands. After installing the runtime, sign out of your machine and sign back in to update your permissions automatically. Until then, use **sudo** in front of any `iotedge` the commands.
+
+On resource constrained devices, it is highly recommended that *OptimizeForPerformance* environment variable is set to *false* as per instructions in the [troubleshooting guide][lnk-trouble].
+
 ## Next steps
 
-If you are having problems with the Edge runtime installing properly, checkout the [troubleshooting][lnk-trouble] page.
+If you are having problems with the Edge runtime installing properly, refer to the [troubleshooting][lnk-trouble] page.
 
 <!-- Links -->
 [lnk-dcs]: how-to-register-device-portal.md

articles/iot-edge/how-to-install-iot-edge-linux.md

@@ -8,20 +8,24 @@ ms.reviewer: veyalla
 ms.service: iot-edge
 services: iot-edge
 ms.topic: conceptual
-ms.date: 08/14/2018
+ms.date: 08/27/2018
 ms.author: kgremban
 ---
 # Install the Azure IoT Edge runtime on Linux (x64)
 
-The Azure IoT Edge runtime is deployed on all IoT Edge devices. It has three components. The **IoT Edge security daemon** provides and maintains security standards on the Edge device. The daemon starts on every boot and bootstraps the device by starting the IoT Edge agent. The **IoT Edge agent** facilitates deployment and monitoring of modules on the Edge device, including the IoT Edge hub. The **IoT Edge hub** manages communications between modules on the IoT Edge device, and between the device and IoT Hub.
+The Azure IoT Edge runtime is what turns a device into an IoT Edge device. The runtime can be deployed on devices as small as Raspberry Pis or as large as industrial servers. Once a device is configured with the IoT Edge runtime, it can start receiving code deployments from the cloud. 
 
-This article lists the steps to install the Azure IoT Edge runtime on your Linux x64 (Intel/AMD) Edge device.
+To learn more about how the IoT Edge runtime works and what components are included, see [Understand the Azure IoT Edge runtime and its architecture](iot-edge-runtime.md).
+
+This article lists the steps to install the Azure IoT Edge runtime on your Linux x64 (Intel/AMD) Edge device. Refer to [Azure IoT Edge support](support.md#operating-systems) for a list of AMD64 operating systems that are currently supported. 
 
 >[!NOTE]
 >Packages in the Linux software repositories are subject to the license terms located in each package (/usr/share/doc/*package-name*). Read the license terms prior to using the package. Your installation and use of the package constitutes your acceptance of these terms. If you do not agree with the license terms, do not use the package.
 
 ## Register Microsoft key and software repository feed
 
+Depending on your operating system, choose the appropriate scripts to prepare your device for the IoT Edge runtime installation. 
+
 ### Ubuntu 16.04
 
 ```cmd/sh
@@ -73,24 +77,42 @@ sudo apt-get install moby-cli
 
 ## Install the Azure IoT Edge Security Daemon
 
-Commands below will also install the standard version of the **iothsmlib** if not already present.
+The **IoT Edge security daemon** provides and maintains security standards on the Edge device. The daemon starts on every boot and bootstraps the device by starting the rest of the IoT Edge runtime. 
+
+The installation command also installs the standard version of the **iothsmlib** if not already present.
+
+Update apt-get.
 
 ```bash
 sudo apt-get update
+```
+
+Install the security daemon. The package is installed at `/etc/iotedge/`.
+
+```bash
 sudo apt-get install iotedge
 ```
 
 ## Configure the Azure IoT Edge Security Daemon
 
+Configure the IoT Edge runtime to link your physical device with a device identity that exists in an Azure IoT hub. 
+
 The daemon can be configured using the configuration file at `/etc/iotedge/config.yaml`. The file is write-protected by default, you might need elevated permissions to edit it.
 
+A single IoT Edge device can be provisioned manually using a device connections string provided by IoT Hub. Or, you can use the Device Provisioning Service to automatically provision devices, which is helpful when you have many devices to provision. Depending on your provisioning choice, choose the appropriate installation script. 
+
+### Option 1: Manual provisioning
+
+To manually provision a device, you need to provide it with a [device connection string][lnk-dcs] that you can create by registering a new device in your IoT hub.
+
+
+Open the configuration file. 
+
 ```bash
 sudo nano /etc/iotedge/config.yaml
 ```
 
-The edge device can be configured manually using a [device connection string][lnk-dcs] or [automatically via Device Provisioning Service][lnk-dps].
-
-* For manual configuration, uncomment the **manual** provisioning mode. Update the value of **device_connection_string** with the connection string from your IoT Edge device.
+Find the provisioning section of the file and uncomment the **manual** provisioning mode. Update the value of **device_connection_string** with the connection string from your IoT Edge device.
 
    ```yaml
    provisioning:
@@ -104,7 +126,27 @@ The edge device can be configured manually using a [device connection string][ln
    #   registration_id: "{registration_id}"
    ```
 
-* For automatic configuration, uncomment the **dps** provisioning mode. Update the values of **scope_id** and **registration_id** with the values from your IoT Hub DPS instance and your IoT Edge device with TPM. 
+Save and close the file. 
+
+   `CTRL + X`, `Y`, `Enter`
+
+After entering the provisioning information in the configuration, restart the daemon:
+
+```bash
+sudo systemctl restart iotedge
+```
+
+### Option 2: Automatic provisioning
+
+To automatically provision a device, [set up Device Provisioning Service and retrieve your device registration ID][lnk-dps] (DPS). Automatic provisioning only works with devices that have a Trusted Platform Module (TPM) chip. For example, Raspberry Pi devices do not come with TPM by default. 
+
+Open the configuration file. 
+
+```bash
+sudo nano /etc/iotedge/config.yaml
+```
+
+Find the provisioning section of the file and uncomment the **dps** provisioning mode. Update the values of **scope_id** and **registration_id** with the values from your IoT Hub Device Provisioning Service and your IoT Edge device with TPM. 
 
    ```yaml
    # provisioning:
@@ -118,15 +160,16 @@ The edge device can be configured manually using a [device connection string][ln
      registration_id: "{registration_id}"
    ```
 
+Save and close the file. 
+
+   `CTRL + X`, `Y`, `Enter`
+
 After entering the provisioning information in the configuration, restart the daemon:
 
-```cmd/sh
+```bash
 sudo systemctl restart iotedge
 ```
 
->[!TIP]
->You need elevated privileges to run `iotedge` commands. Once you sign out of your machine and sign back in the first time after installing the IoT Edge runtime, your permissions are automatically updated. Until then, use **sudo** in front of the commands. 
-
 ## Verify successful installation
 
 If you used the **manual configuration** steps in the previous section, the IoT Edge runtime should be successfully provisioned and running on your device. If you used the **automatic configuration** steps, then you need to complete some additional steps so that the runtime can register your device with your IoT hub on your behalf. For next steps, see [Create and provision a simulated TPM Edge device on a Linux virtual machine](how-to-auto-provision-simulated-device-linux.md#give-iot-edge-access-to-the-tpm).

articles/iot-edge/how-to-install-iot-edge-windows-with-linux.md

@@ -8,14 +8,16 @@ ms.reviewer: veyalla
 ms.service: iot-edge
 services: iot-edge
 ms.topic: conceptual
-ms.date: 08/06/2018
+ms.date: 08/27/2018
 ms.author: kgremban
 ---
 # Install Azure IoT Edge runtime on Windows to use with Linux containers
 
-The Azure IoT Edge runtime is deployed on all IoT Edge devices. It has three components. The **IoT Edge security daemon** provides and maintains security standards on the Edge device. The daemon starts on every boot and bootstraps the device by starting the IoT Edge agent. The **IoT Edge agent** facilitates deployment and monitoring of modules on the Edge device, including the IoT Edge hub. The **IoT Edge hub** manages communications between modules on the IoT Edge device, and between the device and IoT Hub.
+The Azure IoT Edge runtime is what turns a device into an IoT Edge device. The runtime can be deployed on devices as small as Raspberry Pis or as large as industrial servers. Once a device is configured with the IoT Edge runtime, it can start receiving code deployments from the cloud. 
 
-This article lists the steps to install the Azure IoT Edge runtime on your Windows x64 (AMD/Intel) system. Windows support is currently in Preview.
+To learn more about how the IoT Edge runtime works and what components are included, see [Understand the Azure IoT Edge runtime and its architecture](iot-edge-runtime.md).
+
+This article lists the steps to install the Azure IoT Edge runtime with Linux containers on your Windows x64 (AMD/Intel) system. Windows support is currently in Preview.
 
 >[!NOTE]
 Using Linux containers on Windows sytems is not a recommended or supported production configuration for Azure IoT Edge. However, it can be used for development and testing purposes.
@@ -25,6 +27,8 @@ Azure IoT Edge can be used for development and testing on following versions of
   * Windows 10 or newer desktop operating systems.
   * Windows Server 2016 or new server operating systems.
 
+For more information about which operating systems are currently supported, refer to [Azure IoT Edge support](support.md#operating-systems). 
+
 ## Install the container runtime 
 
 Azure IoT Edge relies on a [OCI-compatible][lnk-oci] container runtime (for example, Docker). 
@@ -38,7 +42,7 @@ You can use [Docker for Windows][lnk-docker-for-windows] for development and tes
 
 A single IoT Edge device can be provisioned manually using a device connections string provided by IoT Hub. Or, you can use the Device Provisioning Service to automatically provision devices, which is helpful when you have many devices to provision. Depending on your provisioning choice, choose the appropriate installation script. 
 
-### Install and manually provision
+### Option 1: Install and manually provision
 
 1. Follow the steps in [Register a new Azure IoT Edge device][lnk-dcs] to register your device and retrieve the device connection string. 
 
@@ -53,7 +57,7 @@ A single IoT Edge device can be provisioned manually using a device connections
 
 4. When prompted for a **DeviceConnectionString**, provide the connection string that you retrieved from IoT Hub. Do not include quotes around the connection string. 
 
-### Install and automatically provision
+### Option 2: Install and automatically provision
 
 1. Follow the steps in [Create and provision a simulated TPM Edge device on Windows][lnk-dps] to set up the Device Provisioning Service and retrieve its **Scope ID**, simulate a TPM device and retrieve its **Registration ID**, then create an individual enrollment. Once your device is registered in your IoT Hub, continue with the installation.  
 

articles/iot-edge/how-to-install-iot-edge-windows-with-windows.md

@@ -8,14 +8,16 @@ ms.reviewer: veyalla
 ms.service: iot-edge
 services: iot-edge
 ms.topic: conceptual
-ms.date: 08/06/2018
+ms.date: 08/27/2018
 ms.author: kgremban
 ---
 # Install Azure IoT Edge runtime on Windows to use with Windows containers
 
-The Azure IoT Edge runtime is deployed on all IoT Edge devices. It has three components. The **IoT Edge security daemon** provides and maintains security standards on the Edge device. The daemon starts on every boot and bootstraps the device by starting the IoT Edge agent. The **IoT Edge agent** facilitates deployment and monitoring of modules on the Edge device, including the IoT Edge hub. The **IoT Edge hub** manages communications between modules on the IoT Edge device, and between the device and IoT Hub.
+The Azure IoT Edge runtime is what turns a device into an IoT Edge device. The runtime can be deployed on devices as small as Raspberry Pis or as large as industrial servers. Once a device is configured with the IoT Edge runtime, it can start receiving code deployments from the cloud. 
 
-This article lists the steps to install the Azure IoT Edge runtime on your Windows x64 (AMD/Intel) system. 
+To learn more about how the IoT Edge runtime works and what components are included, see [Understand the Azure IoT Edge runtime and its architecture](iot-edge-runtime.md).
+
+This article lists the steps to install the Azure IoT Edge runtime with Windows containers on your Windows x64 (AMD/Intel) system. 
 
 Windows support is currently in Preview.
 
@@ -24,6 +26,8 @@ Azure IoT Edge with Windows containers can be used with:
   * Windows 10/IoT Enterprise/IoT Core with April 2018 update (Build 17134).
   * Windows Server 1803
 
+For more information about which operating systems are currently supported, refer to [Azure IoT Edge support](support.md#operating-systems).
+
 ## Install the container runtime 
 
 >[!NOTE]