edits part 4 122320

Author: censullo

docs/partner_editable/architecture.adoc

@@ -10,17 +10,17 @@ image::../images/architecture_diagram.png[architecture_diagram,width=100%,height
 
 As shown in <<architecture_diagram>>, this Quick Start sets up a serverless AWS Cloud environment that includes the following components:
 
-* Amazon API Gateway to receive Git webhook requests and forward requests to AWS Lambda.
-* An AWS Lambda function to process Git webhook requests and invoke AWS CodeBuild.
+* Amazon API Gateway to receive Git webhook requests and forward them to AWS Lambda.
+* An AWS Lambda function to process Git webhook requests from API Gateway and invoke an AWS CodeBuild project.
 * AWS Identity and Access Management (IAM) roles required by Lambda and API Gateway (not pictured). 
-* A CodeBuild project to connect to the Git service, then retrieve, zip, and upload Git repository code to Amazon Simple Storage Service (Amazon S3).
-* An AWS Key Management Service (AWS KMS) private key to encrypt the SSH key used by AWS CodeBuild to connect to the Git repository using SSH (Secure Shell).
-* Two Amazon Simple Storage Service (S3) buckets: one for Git repository contents, and another for the AWS KMS key. 
+* A CodeBuild project to connect to your Git service, then retrieve, zip, and upload Git repository code to Amazon Simple Storage Service (Amazon S3).
+* An AWS Key Management Service (AWS KMS) key to encrypt and decrypt the SSH keys used by CodeBuild to connect to your Git repository using SSH (Secure Shell).
+* Two Amazon Simple Storage Service (S3) buckets: one for Git repository contents, and another for encrypted SSH keys. 
 * Two Lambda-backed AWS CloudFormation custom resources (not pictured). One generates an SSH key pair, encrypts it using AWS KMS, and uploads it to Amazon S3. The second deletes the contents of the S3 buckets when you delete the CloudFormation stack. If you need backups, ensure that you copy S3 bucket contents before deleting the stack.
 
 [NOTE]
 ========
 * The inline permissions attached to the IAM roles are scoped using the http://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege[least privilege] model.
-* The CodeBuild project must be able to communicate with your Git repository. For example, you can employ a SaaS-based Git service to which CodeBuild can connect over the internet.
+* The CodeBuild project must be able to communicate with your Git repository. For example, you can employ a SaaS-based Git service like GitHub to which CodeBuild can connect over the internet.
 * The Git repository S3 bucket this Quick Start deploys has versioning enabled, and all previous versions are retained indefinitely. To modify the retention period, see http://docs.aws.amazon.com/AmazonS3/latest/user-guide/create-lifecycle.html[How do I create a lifecycle rule for an S3 bucket?].
 ========

docs/partner_editable/deploy_steps.adoc

@@ -8,27 +8,28 @@
 
 . https://fwd.aws/mDMrd[Launch the AWS CloudFormation template] into your AWS account.
 
-NOTE: You are responsible for the cost of the AWS services used while running this Quick Start reference deployment. There is no additional cost for using this Quick Start. Prices are subject to change. See the pricing pages for each AWS service you will be using in this Quick Start for full details.
+NOTE: You are responsible for the cost of the AWS services used while running this Quick Start reference deployment. There is no additional cost for using this Quick Start. Prices are subject to change. See the pricing pages for each AWS service you use in this Quick Start for full details.
 
+:xrefstyle: short
 [start=2]
-. Check the region that’s displayed in the upper-right corner of the navigation bar, and change it if necessary. This is where the network infrastructure will be built. The template is launched in the US East (Ohio) Region by default.
+. Check the Region that’s displayed in the upper-right corner of the navigation bar, and change it if necessary. This Region is where the Quick Start infrastructure is built. The template for this Quick Start is launched in the US East (Ohio) Region by default.
 . On the *Select Template* page, keep the default setting for the template URL, and then choose *Next*.
-. On the *Specify Details* page, change the stack name if needed. Review the parameters for the template. Provide values for the parameters that require input. For all other parameters, review the default settings and customize them as necessary. When you finish reviewing and customizing the parameters, choose *Next*.
+. On the *Specify Details* page, change the stack name if needed. Review the parameters for the template. Provide values for the parameters that require input. For all other parameters, review the default settings and customize them as necessary. After reviewing and customizing the parameters, choose *Next*.
 . On the *Options* page, you can https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-resource-tags.html[specify tags] (key-value pairs) for resources in your stack and https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-console-add-tags.html[set advanced options]. When you’re done, choose *Next*.
-. On the *Review* page, review and confirm the template settings. Under *Capabilities*, select the check box to acknowledge that the template will create IAM resources.
+. On the *Review* page, review and confirm the template settings. Under *Capabilities*, select the check box to acknowledge that the template creates IAM resources.
 . Choose *Create* to deploy the stack. The stack takes approximately 15 minutes to create.
 . Monitor the status of the stack. When the status is *CREATE_COMPLETE*, the webhook resources are ready.
-. The *Outputs* tab for the stack contain the two webhook endpoint URLs, the output bucket name, and the public SSH key, as illustrated in Figure 4.
+. The *Outputs* tab for the stack contain the endpoint URL, the output S3 bucket name, and the public SSH key, as shown in <<outputs_tab>>.
 
 NOTE: You can also https://fwd.aws/wr8Gg[download the template] to use it as a starting point for your own implementation.
 
 === Configuring Git services
 
-After deploying the Quick Start, set up a webhook in the Git repository. 
+After deploying the Quick Start, set up a webhook in your Git repository. 
 
 To configure a webhook, you need *GitPullWebHookApi* and *PublicSSHKey*. You can find these on the *Outputs* tab on the AWS CloudFormation console after deploying the Quick Start.
 
-:xrefstyle: short
+
 [#outputs_tab]
 .Outputs tab on the AWS CloudFormation console
 [link=images/outputs_tab.png]
@@ -41,7 +42,7 @@ The instructions for setting up webhooks and deployment keys vary by Git service
 
 === Configuring AWS services
 
-After deploying the Quick Start, configure the AWS services in your workload to use the S3 object as a source. 
+After deploying the Quick Start, configure the AWS services in your workload to use the Git repository S3 bucket as a source. 
 
 As shown in <<outputs_tab>>, the *Outputs* tab in the AWS CloudFormation console includes *OutputBucketName*. This output is an S3 key that forms the base of the path to the .zip file of your repository code. The S3 key is in the following format:
 
@@ -50,4 +51,4 @@ S3://output-bucket-name/git-user/git-repository/git-user_git-repository.zip
 ```
 Here, `git-user` is the owner or path prefix of the repository. In some Git services, this may be an organization name. However, some Git services do not return a Git user or organization for a repository. In these cases, you can omit the `git-user` parts of the path.
 
-The instructions for linking an AWS service to the S3 object vary. For links to AWS service documentation, see link:#aws-services[AWS Services] later in this guide.
+The instructions for linking an AWS service to an S3 object vary. For links to AWS service documentation, see link:#aws-services[AWS Services] later in this guide.

docs/partner_editable/faq_troubleshooting.adoc

@@ -6,13 +6,13 @@
 
 *A.* If AWS CloudFormation fails to create the stack, we recommend that you relaunch the template with *Rollback on failure* set to *Disabled*. (This setting is under *Advanced* on the *Options* page of the AWS CloudFormation console.) With this setting, the stack’s state is retained and the instance remains running so you can troubleshoot the issue.
 
-WARNING: When you set *Rollback on failure* to *Disabled*, you continue to incur AWS charges for this stack. Ensure that you delete the stack when after troubleshooting.
+WARNING: When you set *Rollback on failure* to *Disabled*, you continue to incur AWS charges for this stack. Ensure that you delete the stack after troubleshooting.
 
 For additional information, see https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/troubleshooting.html[Troubleshooting AWS CloudFormation^] on the AWS website.
 
 == Troubleshooting
 
-If your commits are not being pushed through to Amazon S3, do the following:
+If commits to your repository do not show up in Amazon S3, do the following:
 
 * Check the security parameters and endpoint in your Git webhook configuration. See link:#configuring_git_services[Configuring Git services] earlier in this guide and consult your Git service documentation for help configuring webhooks.
 * Check the Lambda logs for errors. These are stored in Amazon CloudWatch Logs. For help accessing them, see https://docs.aws.amazon.com/lambda/latest/dg/monitoring-cloudwatchlogs.html[Accessing Amazon CloudWatch logs for AWS Lambda].

docs/partner_editable/product_description.adoc

@@ -1,14 +1,4 @@
 
-:xrefstyle: short
-After deploying this Quick Start and configuring a webhook in your Git repository, when code is pushed to the repository, the Git service sends an HTTPS POST request to the link:#_webhook_endpoints[endpoint]. The POST request contains JavaScript Object Notation (JSON) data about the push operation, including the repository details, that the AWS CodeBuild project uses to fetch the latest version of your repository.
-
-[#using_webhooks]
-.Using webhooks to  code commits
-[link=images/using_webhooks.png]
-image::../images/using_webhooks.png[using_webhooks,width=647,height=266]
-
-When a POST request is received, an AWS Lambda function and AWS CodeBuild project work together to retrieve, zip, and upload the Git repository to Amazon S3.
-
-NOTE: The AWS CodeBuild project deployed by this Quick Start must be able to communicate with your Git repository using a Git service. For example, you can use a SaaS-based Git service that AWS CodeBuild can reach through the internet.
-
+After deploying this Quick Start and configuring a webhook in your Git service, when a Git user pushes changes to your repository, the Git service sends an HTTPS POST request to the HTTPS endpoint. The endpoint is a URL the Quick Start creates that you use to link:#configuring_git_services[configure a Git webhook]. The HTTPS POST request contains JavaScript Object Notation (JSON) data about the push that invoked the webhook action. After the request is accepted by Amazon API Gateway, it is passed to an AWS Lambda function that triggers an AWS CodeBuild project. The CodeBuild project retrieves the latest version of your repository, zips it, and uploads it to an Amazon S3 bucket. 
 
+For more information about the components that this Quick Start deploys, see the link:#architecture[Architecture] section later in this guide.