Review aio get-started to improve new user experience

Author: kgremban

articles/iot-operations/get-started/quickstart-deploy.md

@@ -15,7 +15,7 @@ ms.date: 01/31/2024
 
 [!INCLUDE [public-preview-note](../includes/public-preview-note.md)]
 
-In this quickstart, you will deploy a suite of IoT services to an Azure Arc-enabled Kubernetes cluster so that you can remotely manage your devices and workloads. Azure IoT Operations Preview is a digital operations suite of services that includes Azure IoT Orchestrator Preview. This quickstart guides you through using Orchestrator to deploy these services to a Kubernetes cluster. At the end of the quickstart, you have a cluster that you can manage from the cloud that's generating sample data to use in the following quickstarts.
+In this quickstart, you will deploy a suite of IoT services to an Azure Arc-enabled Kubernetes cluster so that you can remotely manage your devices and workloads. Azure IoT Operations is a digital operations suite of services that includes Azure IoT Orchestrator Preview. This quickstart guides you through using Orchestrator to deploy these services to a Kubernetes cluster. At the end of the quickstart, you have a cluster that you can manage from the cloud that generates sample data to use in the following quickstarts.
 
 The services deployed in this quickstart include:
 
@@ -30,26 +30,36 @@ The services deployed in this quickstart include:
 
 The following quickstarts in this series build on this one to define sample assets, data processing pipelines, and visualizations. If you want to deploy Azure IoT Operations to run your own workloads, see [Prepare your Azure Arc-enabled Kubernetes cluster](../deploy-iot-ops/howto-prepare-cluster.md) and [Deploy Azure IoT Operations Preview extensions to a Kubernetes cluster](../deploy-iot-ops/howto-deploy-iot-operations.md).
 
+## Before you begin
+
+This series of quickstarts is intended to give you an opportunity to evaluate an end-to-end scenario with Azure IoT Operations. In a true development or production environment, these tasks would be performed by multiple teams working together and some tasks require elevated permissions.
+
+For the best new user experience, we recommend using a free Azure subscription so that you have owner permissions over the resources in these quickstarts. We also recommend using GitHub Codespaces as a virtual environment in which you can quickly begin deploying resources and running commands without installing new tools on your own machines.
+
+Once you're ready to learn more about the individual roles and tasks, the how-to guides provide more specific implementation and permissions details.
+
 ## Prerequisites
 
 Review the prerequisites based on the environment you use to host the Kubernetes cluster.
 
-For this quickstart, we recommend GitHub Codespaces as a quick way to get started in a virtual environment without installing new tools. Or, use Azure Kubernetes Service (AKS) Edge Essentials to create a cluster on Windows devices or K3s on Ubuntu Linux devices.
+For this quickstart, we recommend using a virtual environment as a quick way to get started without installing new tools.
 
-As part of this quickstart, you create a cluster in either Codespaces, AKS Edge Essentials, or Linux. If you want to reuse a cluster that you've deployed Azure IoT Operations to before, refer to the steps in [Clean up resources](#clean-up-resources) to uninstall Azure IoT Operations before continuing.
+As part of this quickstart, you create a cluster in either GitHub Codespaces, AKS Edge Essentials, or K3s on Ubuntu Linux. If you want to reuse a cluster that you've deployed Azure IoT Operations to before, refer to the steps in [Clean up resources](#clean-up-resources) to uninstall Azure IoT Operations before continuing.
 
 # [Virtual](#tab/codespaces)
 
 * An Azure subscription. If you don't have an Azure subscription, [create one for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F) before you begin.
 
 * A [GitHub](https://github.com) account.
 
-# [Windows](#tab/windows)
+* Visual Studio Code installed on your development machine. For more information, see [Download Visual Studio Code](https://code.visualstudio.com/download).
 
-* You'll use the `AksEdgeQuickStartForAio.ps1` script to set up an AKS Edge Essentials single-machine K3S Linux-only cluster. Ensure that your machine has a minimum of 10 GB RAM, 4 vCPUs, and 40 GB free disk space. To learn more, see the [AKS Edge Essentials system requirements](/azure/aks/hybrid/aks-edge-system-requirements).
+# [Windows](#tab/windows)
 
 * An Azure subscription. If you don't have an Azure subscription, [create one for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F) before you begin.
 
+* Ensure that your machine has a minimum of 10 GB RAM, 4 vCPUs, and 40 GB free disk space. To learn more, see the [AKS Edge Essentials system requirements](/azure/aks/hybrid/aks-edge-system-requirements).
+
 * Azure CLI installed on your development machine. For more information, see [How to install the Azure CLI](/cli/azure/install-azure-cli).
 
   This quickstart requires Azure CLI version 2.46.0 or higher. Use `az --version` to check your version and `az upgrade` to update if necessary.

articles/iot-operations/includes/connect-cluster.md

@@ -11,7 +11,7 @@ ms.custom: include file, ignite-2023, devx-track-azurecli
 
 To connect your cluster to Azure Arc:
 
-1. On the machine where you deployed the Kubernetes cluster, sign in with Azure CLI:
+1. On the machine where you deployed the Kubernetes cluster or your codespace terminal, sign in with Azure CLI:
 
    ```azurecli
    az login
@@ -27,7 +27,7 @@ To connect your cluster to Azure Arc:
    ```bash
    # Azure region where the created resource group will be located
    # Currently supported regions: "eastus", "eastus2", "westus", "westus2", "westus3", "westeurope", or "northeurope"
-   export LOCATION="WestUS3"
+   export LOCATION="<REGION>"
    ```
 
    ```bash
@@ -64,13 +64,13 @@ To connect your cluster to Azure Arc:
    az group create --location $LOCATION --resource-group $RESOURCE_GROUP --subscription $SUBSCRIPTION_ID
    ```
 
-1. Use the [az connectedk8s connect](/cli/azure/connectedk8s#az-connectedk8s-connect) command to Arc-enable your Kubernetes cluster and manage it in the resource group you created in the previous step:
+1. Use the [az connectedk8s connect](/cli/azure/connectedk8s#az-connectedk8s-connect) command to Arc-enable your Kubernetes cluster and manage it as part of your Azure resource group:
 
    ```azurecli
    az connectedk8s connect -n $CLUSTER_NAME -l $LOCATION -g $RESOURCE_GROUP --subscription $SUBSCRIPTION_ID
    ```
 
-1. Get the `objectId` of the Microsoft Entra ID application that the Azure Arc service uses. Run this command in the [Azure Cloud Shell](https://portal.azure.com/#cloudshell) or on your local machine:
+1. Get the `objectId` of the Microsoft Entra ID application that the Azure Arc service uses. Run this command in the [Azure Cloud Shell](https://portal.azure.com/#cloudshell), on your local machine, or in a Cloudspaces terminal:
 
    ```azurecli
    az ad sp show --id bc313c14-388c-4e7d-a58e-70017303ee3b --query id -o tsv

articles/iot-operations/includes/prepare-codespaces.md

@@ -10,7 +10,7 @@ ms.custom:
   - ignite-2023
 ---
 
-Use GitHub Codespaces to try Azure IoT Operations on a Kubernetes cluster without installing anything on your local machine. Use the **explore-iot-operations** codespace that is preconfigured with:
+Use GitHub Codespaces to try Azure IoT Operations on a Kubernetes cluster without installing anything on your local machine. The **Azure-Samples/explore-iot-operations** codespace is preconfigured with:
 
 - [K3s](https://k3s.io/) running in [K3d](https://k3d.io/) for a lightweight Kubernetes cluster
 - [Azure CLI](/cli/azure/install-azure-cli)
@@ -22,20 +22,24 @@ Use GitHub Codespaces to try Azure IoT Operations on a Kubernetes cluster withou
 
 To get started with your codespace:
 
-1. Create the codespace in GitHub Codespaces.
+1. Create a codespace in GitHub Codespaces.
 
-   [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/Azure-Samples/explore-iot-operations?quickstart=1)
+   [![Create an explore-iot-operations codespace](https://github.com/codespaces/badge.svg)](https://codespaces.new/Azure-Samples/explore-iot-operations?quickstart=1)
 
 1. Provide the following details to configure your codespace:
 
    | Parameter | Value |
    | --------- | ----- |
    | SUBSCRIPTION_ID | Your Azure subscription ID. |
    | RESOURCE_GROUP | A name for a new Azure resource group where your cluster will be created. Remember the resource group name to use in the following CLI commands. |
-   | LOCATION | An Azure region close to you. The following regions are supported in public preview: eastus, eastus2, westus, westus2, westus3, westeurope, or northeurope. Remember the region you choose to use in the following CLI commands. |
+   | LOCATION | An Azure region close to you. The following regions are supported in public preview: eastus, eastus2, westus, westus2, westus3, westeurope, or northeurope. Remember the region to use in the following CLI commands. |
 
 1. Select **Create new codespace**.
 
 1. Once the codespace is ready, select the menu button at the top left, then select **Open in VS Code Desktop**.
 
    ![Open VS Code desktop](media/prepare-codespaces/open-in-vs-code-desktop.png)
+
+1. In Visual Studio Code, select **View** > **Terminal**.
+
+   Use this terminal to run all of the command line and CLI commands for managing your cluster.