Updates to the app host aritcle.

docs/app-host-overview.md

@@ -1,29 +1,29 @@
 ---
 title: .NET Aspire orchestration overview
-description: Learn the fundamental concepts of .NET Aspire orchestration.
-ms.date: 11/11/2023
+description: Learn the fundamental concepts of .NET Aspire orchestration and explore the various APIs to express resource references.
+ms.date: 11/13/2023
 ms.topic: overview
 ms.prod: dotnet
 ---
 
 # .NET Aspire orchestration overview
 
-.NET Aspire provides APIs for expressing resources and dependencies within your distributed application.
+.NET Aspire provides APIs for expressing resources and dependencies within your distributed application. In addition to these APIs, there's tooling that enables some compelling scenarios.
 
 Before continuing, consider some common terminology used in .NET Aspire:
 
 - **App model**: A collection of resources that make up your distributed application (`DistributedApplication`). For a more formal definition, see [App model](#app-model).
 - **App host/Orchestrator project**: The .NET project that orchestrates the _app model_, named with the _*.AppHost_ suffix (by convention).
-- **Resource**: A [resource](#built-in-resource-types) is a dependent part of your distributed application, such as a project, container, or an executable.
-- **Reference**: A reference defines a connection between resources. For more information, see [Reference resources](#reference-resources).
+- **Resource**: A [resource](#built-in-resource-types) represents a part of an application whether it be a .NET project, container, or executable, or some other resource like a database, cache, or cloud service (such as a storage service).
+- **Reference**: A reference defines a connection between resources, expressed as a dependency. For more information, see [Reference resources](#reference-resources).
 
 ## App model
 
-.NET Aspire empowers you to seamlessly build, provision, deploy, configure, test, run, and observe your cloud application. This is achieved through the utilization of an application model (app model) that outlines the resources in your app and their relationships. These resources encompass projects, executables, containers, as well as external services and cloud resources that your app depends on. Within every .NET Aspire app, there is a designated [AppHost project](#orchestration-project), where the app model is precisely defined using methods available on the `IDistributedApplicationBuilder`. This builder is obtained by invoking `DistributedApplication.CreateBuilder(args)`.
+.NET Aspire empowers you to seamlessly build, provision, deploy, configure, test, run, and observe your cloud application. This is achieved through the utilization of an _app model_ that outlines the resources in your app and their relationships. These resources encompass projects, executables, containers, as well as external services and cloud resources that your app depends on. Within every .NET Aspire app, there is a designated [AppHost project](#orchestration-project), where the app model is precisely defined using methods available on the `IDistributedApplicationBuilder`. This builder is obtained by invoking `DistributedApplication.CreateBuilder(args)`.
 
-## Orchestration project
+## App host project
 
-The app host project handles running all of the projects that are part of the .NET Aspire application. The following code describes an application with two projects and a redis cache:
+The app host project handles running all of the projects that are part of the .NET Aspire application. In other words, it's responsible for orchestrating all apps within the app model. The following code describes an application with two projects and a Redis cache:
 
 ```csharp
 var builder = DistributedApplication.CreateBuilder(args);
@@ -39,11 +39,11 @@ builder.AddProject<Projects.AspireApp_Web>("webfrontend")
 builder.Build().Run();
 ```
 
-The help visualize the relationship between the app host project and the other projects, consider the following diagram:
+The help visualize the relationship between the app host project and the resources it describes, consider the following diagram:
 
 :::image type="content" source="media/app-host-resource-diagram.png" lightbox="media/app-host-resource-diagram.png" alt-text="The relationship between the projects in the .NET Aspire Starter Application template.":::
 
-Each resource must be uniquely named. This diagram shows each resource and the relationships between them. The container resource is named "cache" and the project resources are named "apiservice" and "webfrontend". The web frontend project references the cache and API service projects.
+Each resource must be uniquely named. This diagram shows each resource and the relationships between them. The container resource is named "cache" and the project resources are named "apiservice" and "webfrontend". The web frontend project references the cache and API service projects. By expressing a reference in this way, the web frontend project is saying that it depends on these two resources.
 
 ## Built-in resource types
 
@@ -75,8 +75,7 @@ builder.AddProject<Projects.AspireApp_Web>("webfrontend")
     .WithReference(cache);
 ```
 
-The "webfrontend" project resource uses `WithReference` to add a dependency on the "cache" container resource. These dependencies can represent connection strings or service discovery information. In the preceding example, an environment variable is injected into the "webfronend" resource with the name `ConnectionStrings__cache`. This environment variable contains
-a connection string that the webfrontend can use to connect to redis via the .NET Aspire Redis component, for example, `ConnectionStrings__cache="localhost:6379"`.
+The "webfrontend" project resource uses `WithReference` to add a dependency on the "cache" container resource. These dependencies can represent connection strings or service discovery information. In the preceding example, an environment variable is injected into the "webfronend" resource with the name `ConnectionStrings__cache`. This environment variable contains a connection string that the webfrontend can use to connect to redis via the .NET Aspire Redis component, for example, `ConnectionStrings__cache="localhost:6379"`.
 
 ### Connection string and endpoint references
 
@@ -117,11 +116,11 @@ var apiservice = builder.AddProject<Projects.AspireApp_ApiService>("apiservice")
 |--|--|
 | `WithReference(endpoint)` | `services__myapp__0=http://_http.localhost:8034` |
 
-### APIs to add resources
+### APIs for adding and expressing resources
 
 Beyond the base resource types, `ProjectResource`, `ContainerResource`, and `ExecutableResource`, .NET Aspire provides extension methods to add common resources to your app model. The following table lists the methods and their corresponding resource types:
 
-**Cloud agnostic resources available in the [Aspire.Hosting](https://www.nuget.org/packages/Aspire.Hosting) NuGet package (available by default in .NET Aspire templates):**
+**Cloud-agnostic resources available in the [📦 Aspire.Hosting](https://www.nuget.org/packages/Aspire.Hosting) NuGet package (available by default in .NET Aspire templates with the AppHost project):**
 
 | Method | Resource type | Description |
 |--|--|--|
@@ -135,7 +134,7 @@ Beyond the base resource types, `ProjectResource`, `ContainerResource`, and `Exe
 | `AddSqlServerContainer` | `SqlServerContainerResource` | Adds a SQL Server container resource. |
 | `AddSqlServerContainer(...).AddDatabase` | `SqlServerDatabaseResource` | Adds a SQL Server database resource. |
 
-**Azure specific resources available in the [Aspire.Hosting.Azure](https://www.nuget.org/packages/Aspire.Hosting.Azure) NuGet package:**
+**Azure specific resources available in the [📦 Aspire.Hosting.Azure](https://www.nuget.org/packages/Aspire.Hosting.Azure) NuGet package:**
 
 | Method | Resource type | Description |
 |--|--|--|