Improve clarity of quickstarts

Author: kgremban

articles/iot-edge/quickstart-linux.md

@@ -4,14 +4,11 @@ description: In this quickstart, learn how to deploy prebuilt code remotely to a
 author: kgremban
 manager: philmea
 ms.author: kgremban
-ms.date: 08/14/2018
+ms.date: 10/14/2018
 ms.topic: quickstart
 ms.service: iot-edge
 services: iot-edge
 ms.custom: mvc
-
-experimental: true
-experiment_id: 21cb7321-bcff-4b
 ---
 
 # Quickstart: Deploy your first IoT Edge module to a Linux x64 device
@@ -56,9 +53,11 @@ IoT Edge device:
 * A Linux device or virtual machine to act as your IoT Edge device. If you want to create a virtual machine in Azure, use the following command to get started quickly:
 
    ```azurecli-interactive
-   az vm create --resource-group IoTEdgeResources --name EdgeVM --image Canonical:UbuntuServer:16.04-LTS:latest --admin-username azureuser --generate-ssh-keys --size Standard_B1ms
+   az vm create --resource-group IoTEdgeResources --name EdgeVM --image Canonical:UbuntuServer:16.04-LTS:latest --admin-username azureuser --generate-ssh-keys --size Standard_DS1_v2
    ```
 
+   When you create a new virtual machine, make a note of the **publicIpAddress**, which is provided as part of the create command output. You use this publicIpAddress to connect to the virtual machine later in the quickstart.
+
 ## Create an IoT hub
 
 Start the quickstart by creating your IoT hub with Azure CLI.
@@ -73,7 +72,7 @@ The following code creates a free **F1** hub in the resource group **IoTEdgeReso
    az iot hub create --resource-group IoTEdgeResources --name {hub_name} --sku F1 
    ```
 
-   If you get an error because there's already one free hub in your subscription, change the SKU to **S1**.
+   If you get an error because there's already one free hub in your subscription, change the SKU to **S1**. If you get an error that the IoT Hub name is not available, it means that someone else already has a hub with that name. Try a new name. 
 
 ## Register an IoT Edge device
 
@@ -90,13 +89,15 @@ Since IoT Edge devices behave and can be managed differently than typical IoT de
    az iot hub device-identity create --hub-name {hub_name} --device-id myEdgeDevice --edge-enabled
    ```
 
-1. Retrieve the connection string for your device, which links your physical device with its identity in IoT Hub. 
+   If you get an error about iothubowner policy keys, make sure that your cloud shell is running the latest version of the azure-cli-iot-ext extension. 
+
+2. Retrieve the connection string for your device, which links your physical device with its identity in IoT Hub. 
 
    ```azurecli-interactive
    az iot hub device-identity show-connection-string --device-id myEdgeDevice --hub-name {hub_name}
    ```
 
-1. Copy the connection string and save it. You'll use this value to configure the IoT Edge runtime in the next section. 
+3. Copy the connection string and save it. You'll use this value to configure the IoT Edge runtime in the next section. 
 
 ## Install and start the IoT Edge runtime
 
@@ -107,7 +108,15 @@ The IoT Edge runtime is deployed on all IoT Edge devices. It has three component
 
 During the runtime configuration, you provide a device connection string. Use the string that you retrieved from the Azure CLI. This string associates your physical device with the IoT Edge device identity in Azure. 
 
-Complete the following steps in the Linux machine or VM that you prepared to function as an IoT Edge device. 
+### Connect to your IoT Edge device
+
+The steps in this section all take place on your IoT Edge device. If you're using your own machine as the IoT Edge device, you can skip this part. If you're using a virtual machine or secondary hardware, you want to connect to that machine now. 
+
+If you created an Azure virtual machine for this quickstart, retrieve the public IP address that was output by the creation command. If you didn't save this information earlier, you can find it by navigating to your virtual machine in the Azure portal, and reading the overview details. Use the following command to connect to your virtual machine:
+
+```azurecli-interactive
+ssh azureuser@{publicIpAddress}
+```
 
 ### Register your device to use the software repository
 

articles/iot-edge/quickstart.md

@@ -9,9 +9,6 @@ ms.topic: quickstart
 ms.service: iot-edge
 services: iot-edge
 ms.custom: mvc
-
-#experimental: true
-#experiment_id: 2c2f48c7-50a9-4e
 ---
 
 # Quickstart: Deploy your first IoT Edge module from the Azure portal to a Windows device - preview
@@ -80,7 +77,7 @@ The following code creates a free **F1** hub in the resource group **IoTEdgeReso
    az iot hub create --resource-group IoTEdgeResources --name {hub_name} --sku F1
    ```
 
-   If you get an error because there's already one free hub in your subscription, change the SKU to **S1**.
+   If you get an error because there's already one free hub in your subscription, change the SKU to **S1**. If you get an error that the IoT Hub name is not available, it means that someone else already has a hub with that name. Try a new name. 
 
 ## Register an IoT Edge device
 
@@ -97,13 +94,15 @@ Since IoT Edge devices behave and can be managed differently than typical IoT de
    az iot hub device-identity create --device-id myEdgeDevice --hub-name {hub_name} --edge-enabled
    ```
 
-1. Retrieve the connection string for your device, which links your physical device with its identity in IoT Hub.
+   If you get an error about iothubowner policy keys, make sure that your cloud shell is running the latest version of the azure-cli-iot-ext extension. 
+
+2. Retrieve the connection string for your device, which links your physical device with its identity in IoT Hub.
 
    ```azurecli-interactive
    az iot hub device-identity show-connection-string --device-id myEdgeDevice --hub-name {hub_name}
    ```
 
-1. Copy the connection string and save it. You'll use this value to configure the IoT Edge runtime in the next section.
+3. Copy the connection string and save it. You'll use this value to configure the IoT Edge runtime in the next section.
 
 ## Install and start the IoT Edge runtime
 
@@ -116,7 +115,9 @@ During the runtime installation, you're asked for a device connection string. Us
 
 The instructions in this section configure the IoT Edge runtime with Linux containers. If you want to use Windows containers, see [Install Azure IoT Edge runtime on Windows to use with Windows containers](how-to-install-iot-edge-windows-with-windows.md).
 
-Complete the following steps in the Windows machine or VM that you prepared to function as an IoT Edge device.
+### Connect to your IoT Edge device
+
+The steps in this section all take place on your IoT Edge device. If you're using your own machine as the IoT Edge device, you can skip this part. If you're using a virtual machine or secondary hardware, you want to connect to that machine now. 
 
 ### Download and install the IoT Edge service
 

includes/iot-edge-deploy-module.md

@@ -5,25 +5,28 @@
  author: kgremban
  ms.service: iot-edge
  ms.topic: include
- ms.date: 08/14/2018
+ ms.date: 10/14/2018
  ms.author: kgremban
  ms.custom: include file
 ---
 
 One of the key capabilities of Azure IoT Edge is being able to deploy modules to your IoT Edge devices from the cloud. An IoT Edge module is an executable package implemented as a container. In this section, you deploy a module that generates telemetry for your simulated device.
 
 1. In the Azure portal, navigate to your IoT hub.
-1. Go to **IoT Edge** under **Automatic Device Management** and select your IoT Edge device.
-1. Select **Set Modules**.
-1. In the **Deployment Modules** section of the **Add Modules** step, click **Add** then select **IoT Edge Module**.
-1. In the **Name** field, enter `tempSensor`.
-1. In the **Image URI** field, enter `mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.0`.
-1. Leave the other settings unchanged, and select **Save**.
+2. Go to **IoT Edge** under **Automatic Device Management** and select your IoT Edge device.
+3. Select **Set Modules**. A three-step wizard opens in the portal, which guides you through adding modules, specifying routes, and reviewing the deployment. 
+4. In the **Add Modules** step of the wizard, find the **Deployment Modules** section. Click **Add** then select **IoT Edge Module**.
+
+   ![Add a new IoT Edge module](./media/iot-edge-deploy-module/add-module.png)
+
+5. In the **Name** field, enter `tempSensor`.
+6. In the **Image URI** field, enter `mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.0`.
+7. Leave the other settings unchanged, and select **Save**.
 
    ![Save IoT Edge module after entering name and image URI](./media/iot-edge-deploy-module/name-image.png)
 
-1. Back in the **Add Modules** step, select **Next**.
-1. In the **Specify routes** step, you should have a default route that sends all messages from all modules to IoT Hub. If not, add the following code then select **Next**.
+8. Back in first step of the wizard, select **Next**.
+9. In the **Specify Routes** step of the wizard, you should have a default route that sends all messages from all modules to IoT Hub. If not, add the following code then select **Next**.
 
    ```json
    {
@@ -33,7 +36,9 @@ One of the key capabilities of Azure IoT Edge is being able to deploy modules to
    }
    ```
 
-1. In the **Review Deployment** step, select **Submit**.
-1. Return to the device details page and select **Refresh**. In addition to the edgeAgent module that was created when you first started the service, you should see another runtime module called **edgeHub** and the **tempSensor** module listed.
+10. In the **Review Deployment** step of the wizard, select **Submit**.
+11. Return to the device details page and select **Refresh**. In addition to the edgeAgent module that was created when you first started the service, you should see another runtime module called **edgeHub** and the **tempSensor** module listed.
+
+   It may take a few minutes for the new modules to show up. The IoT Edge device has to retrieve its new deployment information from the cloud, start the containers, and then report its new status back to IoT Hub. 
 
    ![View tempSensor in list of deployed modules](./media/iot-edge-deploy-module/deployed-modules.png)