docs: Deployment project documentation revisions

mkdocs.yml

@@ -27,12 +27,13 @@ nav:
     - Docker support:
       - Dockerfile generation: docs/docker/docker-generation.md
       - Publishing a Docker image: docs/docker/publish-image.md
-    - Custom Deployment Projects: 
-       - Getting Started: docs/deployment-projects/index.md
-       - Tutorial: docs/deployment-projects/tutorial.md
+    - Deployment Projects:
+       - Overview: docs/deployment-projects/index.md
        - Recipe File: docs/deployment-projects/recipe-file.md
        - CDK Project: docs/deployment-projects/cdk-project.md
     - Integrating with CI/CD: docs/cicd.md
+  - Tutorials:
+    - Customizing deployment projects: tutorials/custom-project.md
   - Troubleshooting Guide:
     - troubleshooting-guide/index.md
     - Missing Dependencies: troubleshooting-guide/missing-dependencies.md
@@ -56,4 +57,4 @@ theme:
 
 markdown_extensions:
   - pymdownx.emoji:
-      emoji_index: !!python/name:materialx.emoji.twemoji
+      emoji_index: !!python/name:materialx.emoji.twemoji

site/content/docs/commands/project.md

@@ -9,9 +9,12 @@
 ### Description
 Generates and saves the [deployment CDK project](../deployment-projects/index.md) in a user provided directory path without proceeding with a deployment. Allows user to customize the CDK project before deploying the application.
 
+* The `--output` switch sets the directory where the deployment project will be saved.
+* The `--project-display-name` switch sets the name that will be shown when the .NET project is being deployed.
+
 ### Examples
 
-Creates a deployment project based on the .NET project in the current directory. The new deployment project will be saved to a sibling directory called CustomDeploymentProject. The project display name _"Team custom deployment project"_ will be displayed to users when selecting a publish target when deploying with the custom deployment project.
+This example creates a deployment project from the .NET project in the current directory. The  deployment project will be saved to a sibling directory called CustomDeploymentProject. The name _"Team custom deployment project"_ will be displayed in the list of the available deployment options.
 
-    dotnet aws deployment-project generate --output ../CustomDeploymentProject --project-display-name "Team custom deployment project" 
+    dotnet aws deployment-project generate --output ../CustomDeploymentProject --project-display-name "Team custom deployment project"
 

site/content/docs/deployment-projects/cdk-project.md

@@ -1,59 +1,22 @@
 # CDK Project
 
-A custom deployment project uses a C# Cloud Development Kit (CDK) project to create the AWS infrastructure as a CloudFormation stack based on the settings provided by the user and to deploy your project to that infrastructure.
+Each deployment project has a C# Cloud Development Kit (CDK) project. This CDK project is used to create the AWS infrastructure as a CloudFormation stack based on the user settings and to deploy your project to that infrastructure.
 
+Read our [tutorial](../../tutorials/custom-project.md) to see how you can customize this CDK project to add additional infrastructure resources for your deployments.
 
-### CDK Refresher
-The following links are useful resources to learn how to write .NET CDK projects.
+### What is AWS CDK?
 
-* [.NET CDK Workshop](https://cdkworkshop.com/40-dotnet.html)
-* [.NET CDK Reference](https://docs.aws.amazon.com/cdk/api/v2/dotnet/api/index.html)
-* [AWS CDK Developer Guide](https://docs.aws.amazon.com/cdk/v2/guide/home.html)
-
-The main concepts to understand about the CDK are the following.
-
-* Stack - this is the top level container for all of the AWS resources represented as constructs. In deployment projects this type is usually the `AppStack` type in the project.
-* Constructs - AWS resources are modeled as constructs. Some constructs are a one-to-one mapping to a single AWS resource. The CDK also has higher level abstractions where a single construct represents a collection of AWS resources that solve a common problem.
-* Construct properties - For every construct there is a properties object that is created first, all necessary values are set and then passed into the constructor of a construct.
-
-
-### Main method in Program.cs
-
-The `Main` method in `Program.cs` for the CDK deployment project must be coded in a certain style to ensure compatibility with the deploy tool. The deploy tool relies on .NET's Configuration system to pass along settings from the deploy tool to the CDK project. In the example below the `ConfigurationBuilder().AddAWSDeployToolConfiguration(app)` method reads the settings that were passed into the project from the deploy tool.
-
-With the configuration read from the deploy tool, the CDK environment is set to the account and region the deploy tool was configured with.
-
-The other major difference from normal CDK projects is the call to `CDKRecipeSetup.RegisterStack`. This is required to stamp the CloudFormation stack with the recipe id that created the stack. Future redeployments can only update existing stacks that were created by the original recipe. It also serializes the settings collected from the deploy tool into the metadata for the CloudFormation stack so redeployments can use the previous settings used for deployment.
+The [AWS Cloud Development Kit (AWS CDK)](https://aws.amazon.com/cdk/) is an open-source software development framework to define your cloud application resources using familiar programming languages.
 
-```
-public static void Main(string[] args)
-{
-    var app = new App();
+The following links are useful resources to learn more about AWS CDK and how to write .NET CDK projects.
 
-    var builder = new ConfigurationBuilder().AddAWSDeployToolConfiguration(app);
-    var recipeProps = builder.Build().Get<RecipeProps<Configuration>>();
-    var appStackProps = new DeployToolStackProps<Configuration>(recipeProps)
-    {
-        Env = new Environment
-        {
-            Account = recipeProps.AWSAccountId,
-            Region = recipeProps.AWSRegion
-        }
-    };
-
-    // The RegisterStack method is used to set identifying information on the stack
-    // for the recipe used to deploy the application and preserve the settings used in the recipe
-    // to allow redeployment. The information is stored as CloudFormation tags and metadata inside
-    // the generated CloudFormation template.
-    CDKRecipeSetup.RegisterStack<Configuration>(new AppStack(app, appStackProps), appStackProps.RecipeProps);
-
-    app.Synth();
-}
-```
+* [AWS CDK Developer Guide](https://docs.aws.amazon.com/cdk/v2/guide/home.html)
+* [.NET CDK Workshop](https://cdkworkshop.com/40-dotnet.html)
+* [.NET CDK Reference](https://docs.aws.amazon.com/cdk/api/v2/dotnet/api/index.html)
 
 ### Layout of a CDK deployment project
 
-The layout of the generated CDK project puts all the code that was used to create the AWS resources defined in the starting recipe in a directory called **Generated**. 
+The layout of the generated CDK project puts all the code that was used to create the AWS resources defined in the starting recipe in a directory called **Generated**.
 
 ![Catagories in AWS Toolkit for Visual Studio](../../assets/images/deployment-project-file-layout.png)
 
@@ -80,7 +43,7 @@ internal AppStack(Construct scope, IDeployToolStackProps<Configuration> props)
     // Create additional CDK constructs here. The recipe's constructs can be accessed as properties on
     // the generatedRecipe variable.
 }
-```        
+```
 
 The `var generatedRecipe = new Recipe(this, props.RecipeProps);` line of code creates all of the AWS resources from the `Generated` directory. Your customizations could create new AWS resources via CDK constructs before or after this line. Typically you would create new resources before this line if you want those resources to be connected to the resources defined in the `Recipe` type. If you need to create new resources that are connected to the resources defined in the `Recipe` then create them after this line. The instance of `Recipe` has public properties for all of the resources that were created in the `Recipe`.
 
@@ -101,8 +64,46 @@ private void CustomizeCDKProps(CustomizePropsEventArgs<Recipe> evnt)
 }
 ```
 
-### Configuration
+### Main method in Program.cs
+
+The `Main` method in `Program.cs` for the CDK deployment project must be coded in a certain style to ensure compatibility with the deploy tool. The AWS Deploy Tool relies on .NET's Configuration system to pass along settings from the deploy tool to the CDK project. In the example below the `ConfigurationBuilder().AddAWSDeployToolConfiguration(app)` method reads the settings that were passed into the project from the deploy tool.
+
+With the configuration read from the deploy tool, the CDK environment is set to the account and region the deploy tool was configured with.
+
+The other major difference from normal CDK projects is the call to `CDKRecipeSetup.RegisterStack`. This is required to stamp the CloudFormation stack with the recipe id that created the stack. Future redeployments can only update existing stacks that were created by the original recipe. It also serializes the settings collected from the deploy tool into the metadata for the CloudFormation stack so redeployments can use the previous settings used for deployment.
+
+```
+public static void Main(string[] args)
+{
+    var app = new App();
+
+    var builder = new ConfigurationBuilder().AddAWSDeployToolConfiguration(app);
+    var recipeProps = builder.Build().Get<RecipeProps<Configuration>>();
+    var appStackProps = new DeployToolStackProps<Configuration>(recipeProps)
+    {
+        Env = new Environment
+        {
+            Account = recipeProps.AWSAccountId,
+            Region = recipeProps.AWSRegion
+        }
+    };
+
+    // The RegisterStack method is used to set identifying information on the stack
+    // for the recipe used to deploy the application and preserve the settings used in the recipe
+    // to allow redeployment. The information is stored as CloudFormation tags and metadata inside
+    // the generated CloudFormation template.
+    CDKRecipeSetup.RegisterStack<Configuration>(new AppStack(app, appStackProps), appStackProps.RecipeProps);
+
+    app.Synth();
+}
+```
+
+### Configuration options
+
+The option settings that are defined in the [recipe file](recipe-file.md) are passed into the CDK project and then deserialized into the `Configuration` object.
+
+When you add new settings to the recipe file, you also need to add the `Id` of the new settings to the `Configuration` object. If you added an `Object` setting with a collection of child settings, first create a new type representing that entire `Object`. For reach child setting id, add a property on the new type. Finally, add a new property on `Configuration` for your new type with the property name being the id of the `Object` setting.
+
+The `Configuration` object follows the same `Generated` directory pattern described above. Custom settings should be added to the partial `Configuration.cs` file outside of the `Generated` directory.
 
-The settings collected in the deploy tool are passed into the CDK project and then deserialized into the `Configuration` object. If you add new settings to the recipe file you will need to add the Id of the new settings to the `Configuration` object. If you added an `Object` setting with a collection of child settings then you need to create a new type with the child setting ids as properties on the new type. Then add a new property on the `Configuration` type for the new type with the property name being the id of the `Object` setting.
 
-The `Configuration` object follows the same `Generated` directory pattern described above. Custom settings should be added to the partial `Configuration.cs` file outside of the `Generated` directory.

site/content/docs/deployment-projects/index.md

@@ -1,45 +1,48 @@
-# Custom Deployment Projects
+# Deployment Projects
 
-AWS Deploy Tool comes with multiple recipes that can deploy your .NET application to [several different AWS compute services](../support.md). These built-in recipes let you configure AWS resources related to your application such as IAM roles, virtual private clouds, and load balancers.
+### What is a deployment recipe?
 
-But what if your application uses additional AWS resources that are not included in the built-in recipes, such as DynamoDB tables or SQS queues? 
+The tool provides intelligent deployment recommendations that are tailored to your specific .NET application. The recommendation rules are defined in the `deployment recipes`. These recipes let you configure a pre-defined set of AWS resources related to your application such as IAM roles, virtual private clouds, load balancers, and other.
 
-You can create a **custom deployment project** to expand one of the built-in recipes to manage additional AWS resources and services. 
+There is a built-in recipe for [each supported project type](../support.md). All recipe definitions are available [on GitHub](https://github.com/aws/aws-dotnet-deploy/tree/main/src/AWS.Deploy.Recipes/RecipeDefinitions).
 
-Once you create a custom deployment project, the AWS Deploy Tool CLI and the AWS Toolkit for Visual Studio will display it alongside the built-in recipes and offer users the same deployment experience.
+### What is a deployment project?
 
-![Custom Deployment Project in AWS Toolkit for Visual Studio](../../assets/images/custom-deployment-project.png)
-_The recommended publish target is a custom deployment project that manages a DynamoDB table in addition to the ASP.NET Core project._
+What if your application uses additional AWS resources that are not included in the built-in recipe, such as DynamoDB tables or SQS queues? In this case, you can extend one of the existing recipes and create a custom `deployment project` to manage additional AWS resources and services.
 
-### Parts of a custom deployment project
+Once you create and customize your deployment project, it will be displayed alongside the built-in recipes as a custom deployment option.
 
-A custom deployment project is comprised of two parts. You can follow the getting start guide on this page or the [tutorial](./tutorial.md) to create these, then refer to the full reference guides below.
+** Before:** _The recommended deployment target is a built-in recipe for ASP.NET Core applications._
 
-* [Recipe file](./recipe-file.md) - a JSON file that drives the user experience in both the deploy tool CLI and AWS Toolkit for Visual Studio.  
-* [.NET CDK project](./cdk-project.md) - a C# project that uses the [AWS Cloud Development Kit (CDK)](https://aws.amazon.com/cdk/) to define the infrastructure that will be created for the deployment project. 
+![Before](../../assets/images/cliBefore.png)
 
-### Getting started
+** After:** _The recommended deployment target is a custom deployment project that manages a DynamoDB table in addition to the ASP.NET Core project._
 
-To create a custom deployment project, execute the following command in the directory of the .NET project you wish to deploy.
+![After](../../assets/images/cliAfterBorder.png)
 
-    dotnet aws deployment-project generate --output <output-directory> --project-display-name <display-name> 
+### Parts of a deployment project
 
-The `--output` switch sets the directory where the deployment project will be saved. Use the `--project-display-name` switch to customize the name of the custom recipe that will be shown to users when the .NET project is being deployed.
+A deployment project consists of two parts. For details, refer to the full reference guides below.
 
-When you run the above command, the tool will display a list of built-in recipes that are compatible with your .NET project. Choose the built-in recipe that is closest to what you wish to deploy. This will be used as the starting point that you can then customize.
+* [Recipe file](./recipe-file.md) - a  JSON configuration file that drives the deployment experience.
+* [.NET CDK project](./cdk-project.md) - a C# project that uses the [AWS Cloud Development Kit (CDK)](https://aws.amazon.com/cdk/) to define the infrastructure that will be created.
 
-Select the starting recipe and then a deployment project will be created in the location of the `--output` directory. Now you can begin customizing the deployment project.
+### Creating a deployment project
 
+To create a custom deployment project, run this command in the directory of the .NET project you wish to deploy. See [`deployment-project` command](../commands/project.md) for more details.
 
-### Add to source control
+    dotnet aws deployment-project generate --output <output-directory> --project-display-name <display-name>
 
-It is important to add the custom deployment project to source control. Redeployments require the custom deployment project to be available to the deployment tooling. If a CloudFormation stack was created from a custom deployment project and that 
-deployment project has been deleted then you will not be able to redeploy to that CloudFormation stack.
+The list of built-in recipes that are compatible with your .NET project will be displayed. Select the recipe that you will use to customize, and a deployment project will be created in the `--output` directory.
 
+   > Note: It is important to add your deployment projects to source control. If your deployment project has been deleted, you will not be able to re-deploy your application to the same CloudFormation stack.
 
-### Searching for custom deployment projects
+Now you can begin customizing the deployment project. See our [step-by-step tutorial](../../tutorials/custom-project.md) for a step-by-step instructions.
 
-When the deploy command is initiated AWS Deploy Tool starts from the solution (.sln) of the .NET project being deployed and searches for custom deployment projects anywhere underneath the solution directory. The custom deployment projects are sent through the deployment tooling's recommendation engine to make sure they are compatible with the .NET project being deployed.
+### Searching for deployment projects
+
+When you run the `dotnet aws deploy` command, the tool searches for deployment projects anywhere underneath the solution (.sln) directory of project you are deploying. It also ensures that each deployment project iscompatible with the .NET project being deployed.
+
+To point to a deployment project that is outside the solution directory, use the `--deployment-project` switch to pass in the path of the deployment project to use. This is common when sharing deployment projects across multiple solutions.
 
-If the custom deployment project is outside of the solution directory use the `--deployment-project` switch for the `dotnet aws deploy` command to pass in the path of the custom deployment project to use. This is common when sharing custom deployment projects across multiple solutions.