Merge pull request #21 from aws-samples/markdown-formatting

yanjieniu · web-flow · commit 4aa8d014ac22 · 2025-09-11T13:20:11.000-07:00
Markdown formatting
diff --git a/instra/tutorial-gen/3b-validate-tutorial.md b/instra/tutorial-gen/3b-validate-tutorial.md
@@ -1,6 +1,26 @@
 # validate tutorial
 
 Validating the content of the AWS CLI tutorial and surface issues about the generated content.
+## formatting and style
+
+Review the tutorial markdown for proper formatting:
+
+**Backticks usage:**
+- Use backticks for all inline code, commands, file paths, resource IDs, status values, and technical terms
+- Examples: `aws s3 ls`, `my-bucket-name`, `ACTIVE`, `~/path/to/file`, `us-east-1`
+- Never use double quotes around backticked content (avoid `"~/file"`, use `~/file`)
+
+**Tilde usage:**
+- Use tildes (`~`) only in code blocks to represent home directory paths
+- Replace tildes meaning "approximately" with the word "approximately" 
+- Examples: "approximately $0.50/hour" not "~$0.50/hour"
+
+**Quotes usage:**
+- Avoid double quotes around technical terms, file names, or commands in descriptive text
+- Use backticks instead: `filename.txt` not "filename.txt"
+- Keep quotes only for actual quoted speech or JSON string values in code blocks
+
+Document any formatting issues in 3-formatting.md.
 
 ## deprecated features
 
@@ -24,4 +44,4 @@ Check the tutorial for issues from an application architecure standpoint. Consid
 
 ## improvements over baseline
 
-Review the baseline tutorial for errors and omissions that were fixed by following the authoring instructions, or caught by validation. Note any issues in 3-baseline.md.
+Review the baseline tutorial for errors and omissions that were fixed by following the authoring instructions, or caught by validation. Note any issues in 3-baseline.md.
diff --git a/instra/tutorial-gen/4-address-feedback.md b/instra/tutorial-gen/4-address-feedback.md
@@ -1,7 +1,22 @@
 # address feedback
 
 Review the instructions for creating a tutorial, and the test results from previous steps. Address issues that arose during testing, as long as they are valid and don't contradict your instructions.
-
+## formatting and style
+
+If the previous step identified any formatting issues, fix them:
+
+**Backticks corrections:**
+- Replace double quotes around technical terms with backticks
+- Remove redundant quotes around backticked content
+- Ensure all commands, file paths, resource IDs, and status values use backticks
+
+**Tilde corrections:**
+- Replace tildes meaning "approximately" with the word "approximately"
+- Ensure tildes are only used in code blocks for home directory paths
+
+**Quote corrections:**
+- Remove unnecessary double quotes around technical terms in descriptive text
+- Maintain quotes only for actual quoted content or JSON strings in code blocks
 ## deprecated features
 
 If the previous step identified any deprecated features, revise the scripts and tutorial to use recommended features that provide the same functionality. If there isn't a newer feature available that provides the same functionality, remove the steps that use the deprecated feature. If the tutorial can't be completed without these steps, generate an error report and ask the user what to do next.
@@ -16,4 +31,4 @@ If the previous step identified any issues with security or architecture best pr
 
 ## readme
 
-Generate a readme file that provides a high level overview of the tutorial and a list of the resources within.
+Generate a readme file that provides a high level overview of the tutorial and a list of the resources within.
diff --git a/tuts/001-lightsail-gs/lightsail-gs.md b/tuts/001-lightsail-gs/lightsail-gs.md
@@ -14,9 +14,9 @@ Before you begin this tutorial, make sure you have the following:
 ### Cost considerations
 
 The resources you create in this tutorial will incur the following approximate costs if left running:
-- Lightsail nano instance: $5.00 USD per month (~$0.0068 per hour)
-- 8 GB additional storage: $0.80 USD per month (~$0.0011 per hour)
-- Instance snapshot: ~$1.00 USD per month for a 20 GB snapshot (~$0.0014 per hour)
+- Lightsail nano instance: $5.00 USD per month (approximately $0.0068 per hour)
+- 8 GB additional storage: $0.80 USD per month (approximately $0.0011 per hour)
+- Instance snapshot: approximately $1.00 USD per month for a 20 GB snapshot (approximately $0.0014 per hour)
 
 The total cost for running this tutorial for one hour is approximately $0.0093 USD. The tutorial includes cleanup instructions to help you avoid ongoing charges. New Lightsail customers may be eligible for the free tier, which includes the $5 USD plan free for one month (up to 750 hours).
 
diff --git a/tuts/003-s3-gettingstarted/s3-gettingstarted.md b/tuts/003-s3-gettingstarted/s3-gettingstarted.md
@@ -114,7 +114,7 @@ aws s3api put-object \
     --metadata "author=AWSDocumentation,purpose=tutorial"
 ```
 
-Notice that we used "documents/" in the key name. This creates a logical folder structure in your bucket, even though S3 is actually a flat object store.
+Notice that we used `documents/` in the key name. This creates a logical folder structure in your bucket, even though S3 is actually a flat object store.
 
 ## Download and verify objects
 
@@ -127,7 +127,7 @@ aws s3api get-object \
     "downloaded-sample-file.txt"
 ```
 
-The command downloads the object and saves it as "downloaded-sample-file.txt" in your current directory. The output provides metadata about the object:
+The command downloads the object and saves it as `downloaded-sample-file.txt` in your current directory. The output provides metadata about the object:
 
 ```
 {
diff --git a/tuts/008-vpc-private-servers-gs/vpc-private-servers-gs.md b/tuts/008-vpc-private-servers-gs/vpc-private-servers-gs.md
@@ -20,10 +20,10 @@ Before you begin this tutorial, you need:
   * At least 1 Application Load Balancer
 
 **Estimated cost**: The resources created in this tutorial will incur charges in your AWS account:
-* NAT Gateways: ~$0.045 per hour, plus data processing charges
-* Elastic IP addresses: Free when associated with running instances, ~$0.005 per hour when not associated
+* NAT Gateways: approximately $0.045 per hour, plus data processing charges
+* Elastic IP addresses: Free when associated with running instances, approximately $0.005 per hour when not associated
 * EC2 instances: Varies by instance type (t3.micro used in this tutorial)
-* Application Load Balancer: ~$0.0225 per hour, plus data processing charges
+* Application Load Balancer: approximately $0.0225 per hour, plus data processing charges
 
 ## Create the VPC and subnets
 
diff --git a/tuts/018-ecs-ec2/ecs-ec2-getting-started.md b/tuts/018-ecs-ec2/ecs-ec2-getting-started.md
@@ -75,7 +75,7 @@ Output:
 }
 ```
 
-The response shows that your cluster has been created successfully and is in the "ACTIVE" status. You can now launch container instances and run tasks in this cluster.
+The response shows that your cluster has been created successfully and is in the `ACTIVE` status. You can now launch container instances and run tasks in this cluster.
 
 **Verify cluster creation**
 
diff --git a/tuts/028-sagemaker-featurestore/sagemaker-featurestore.md b/tuts/028-sagemaker-featurestore/sagemaker-featurestore.md
@@ -625,7 +625,7 @@ These commands first remove all objects from the S3 bucket and then delete the b
 
 The following commands delete the SageMaker execution role that's created for this tutorial.
 
-Note: Replace "123456789012" with your account ID.
+Note: Replace `123456789012` with your account ID.
 ```
 # Delete the custom policy 
 aws iam detach-role-policy \
diff --git a/tuts/030-marketplace-buyer-gs/marketplace-buyer-getting-started.md b/tuts/030-marketplace-buyer-gs/marketplace-buyer-getting-started.md
@@ -55,7 +55,7 @@ aws marketplace-catalog list-entities \
   --query "WordPress"
 ```
 
-This command searches for WordPress-related AMI products in AWS Marketplace. You can replace "WordPress" with any keyword relevant to your needs.
+This command searches for WordPress-related AMI products in AWS Marketplace. You can replace `WordPress` with any keyword relevant to your needs.
 
 **Get details about a specific product**
 
diff --git a/tuts/035-workspaces-personal/workspaces-personal.md b/tuts/035-workspaces-personal/workspaces-personal.md
@@ -28,13 +28,13 @@ Before you begin this tutorial, make sure you have the following:
 Running resources created in this tutorial will incur costs in your AWS account. Approximate costs include:
 
 - **WorkSpaces Personal (Standard bundle with Windows)**:
-  - AlwaysOn mode: ~$35/month
-  - AutoStop mode: ~$9.75/month + $0.26/hour of usage
+  - AlwaysOn mode: approximately $35/month
+  - AutoStop mode: approximately $9.75/month + $0.26/hour of usage
 
 - **Directory Services** (if you need to create one):
-  - AWS Simple AD (Small): ~$36.50/month
-  - AWS Managed Microsoft AD (Standard): ~$292/month
-  - AD Connector: ~$36.50/month
+  - AWS Simple AD (Small): approximately $36.50/month
+  - AWS Managed Microsoft AD (Standard): approximately $292/month
+  - AD Connector: approximately $36.50/month
 
 Additional charges may apply for data transfer, increased storage volumes, and application licensing. For the most current pricing information, see the [Amazon WorkSpaces Pricing page](https://aws.amazon.com/workspaces/pricing/).
 
@@ -70,7 +70,7 @@ Replace `d-abcd1234` with your actual directory ID. The registration process may
 aws workspaces describe-workspace-directories --directory-ids d-abcd1234
 ```
 
-Look for the `"State": "REGISTERED"` field in the output to confirm that registration is complete.
+Look for the `State: REGISTERED` field in the output to confirm that registration is complete.
 
 ## List available WorkSpaces bundles
 
@@ -125,7 +125,7 @@ Creating a WorkSpace can take 20 minutes or more. To check the status of your Wo
 aws workspaces describe-workspaces --workspace-ids ws-abcd1234
 ```
 
-Replace `ws-abcd1234` with your actual WorkSpace ID. Look for the `"State"` field in the output:
+Replace `ws-abcd1234` with your actual WorkSpace ID. Look for the `State` field in the output:
 - `PENDING`: The WorkSpace is still being created
 - `AVAILABLE`: The WorkSpace is ready to use
 - `ERROR`: There was a problem creating the WorkSpace
diff --git a/tuts/037-emr-gs/emr-gs.md b/tuts/037-emr-gs/emr-gs.md
@@ -15,7 +15,7 @@ Before you begin this tutorial, make sure you have the following:
 
 This tutorial creates AWS resources that will incur charges. The estimated cost for running this tutorial for one hour is approximately $0.20 USD (in the US East region), which includes:
 
-- EMR cluster with 3 m5.xlarge instances: ~$0.19/hour
+- EMR cluster with 3 m5.xlarge instances: approximately $0.19/hour
 - S3 storage and requests: <$0.01/hour
 
 To minimize costs, make sure to follow the cleanup instructions at the end of the tutorial to terminate all resources.
@@ -30,7 +30,7 @@ aws ec2 create-key-pair --key-name emr-tutorial-key --query 'KeyMaterial' --outp
 ```
 
 This command creates a new key pair named "emr-tutorial-key" and saves the private key to a file called
-"emr-tutorial-key.pem".
+`emr-tutorial-key.pem`.
 
 **Set proper permissions on the key file**
 
@@ -159,7 +159,7 @@ aws emr create-cluster \
   --log-uri s3://amzndemo-s3-demo-bucket/logs/
 ```
 
-Replace `your-key-pair-name` with the name of your EC2 key pair. In this tutorial, we use "emr-tutorial-key" as your key pair name. 
+Replace `your-key-pair-name` with the name of your EC2 key pair. In this tutorial, we use `emr-tutorial-key` as your key pair name. 
 This command creates a cluster with one primary node and two core nodes, all using m5.xlarge instances. The cluster will have Spark installed and will use the default IAM roles.
 
 The command returns a cluster ID, which you'll need for subsequent operations:
@@ -179,7 +179,7 @@ Check the status of your cluster to see when it's ready:
 aws emr describe-cluster --cluster-id j-1234ABCD5678
 ```
 
-Replace `j-1234ABCD5678` with your actual cluster ID. The cluster is ready when its state changes to "WAITING":
+Replace `j-1234ABCD5678` with your actual cluster ID. The cluster is ready when its state changes to `WAITING`:
 
 ```json
 {
@@ -196,7 +196,7 @@ Replace `j-1234ABCD5678` with your actual cluster ID. The cluster is ready when
 }
 ```
 
-It may take 5-10 minutes for the cluster to reach the "WAITING" state.
+It may take 5-10 minutes for the cluster to reach the `WAITING` state.
 
 ## Submit work to your cluster
 
@@ -230,7 +230,7 @@ Monitor the status of your step. Replace `s-1234ABCDEFGH` with your actual step
 aws emr describe-step --cluster-id j-1234ABCD5678 --step-id s-1234ABCDEFGH
 ```
 
-The step is complete when its state changes to "COMPLETED":
+The step is complete when its state changes to `COMPLETED`:
 
 ```json
 {
@@ -267,7 +267,7 @@ You should see output similar to:
 
 **Download and view results**
 
-Download the results file to your local machine. Replace "part-00000-abcd1234-abcd-1234-abcd-abcd1234abcd-c000.csv" with the actual filename from your "aws s3 ls" output.
+Download the results file to your local machine. Replace `part-00000-abcd1234-abcd-1234-abcd-abcd1234abcd-c000.csv` with the actual filename from your `aws s3 ls` output.
 
 ```bash
 aws s3 cp s3://amzndemo-s3-demo-bucket/results/part-00000-abcd1234-abcd-1234-abcd-abcd1234abcd-c000.csv ./results.csv
@@ -307,14 +307,14 @@ Step 1. Get your current IP address:
    curl -s https://checkip.amazonaws.com
 ```
 
-Step 2. Find your cluster's security group. Replace "j-1234ABCD5678" with your cluster ID.
+Step 2. Find your cluster's security group. Replace `j-1234ABCD5678` with your cluster ID.
 
 ```bash
    aws emr describe-cluster --cluster-id j-1234ABCD5678 --query 'Cluster.Ec2InstanceAttributes.EmrManagedMasterSecurityGroup' --output text
 ```  
  
 
-Step 3. Add SSH access rule to the security group. Replace "sg-xxxxxxxxx" with your security group ID that's returned in Step 2. Replace YOUR_IP_ADDRESS with the IP from
+Step 3. Add SSH access rule to the security group. Replace `sg-xxxxxxxxx` with your security group ID that's returned in Step 2. Replace YOUR_IP_ADDRESS with the IP from
 Step 1.
 
 ```bash
@@ -326,7 +326,7 @@ Step 1.
 
 **Connect via SSH**
 
-Use the following command to connect to the primary node of your cluster. Replace "j-1234ABCD5678" with your actual cluster ID. Replace "~/path/to/your-key-pair.pem" with the path to your key pair file. In this example, we use "~/emr-tutorial-key" as the path to your key pair.
+Use the following command to connect to the primary node of your cluster. Replace `j-1234ABCD5678` with your actual cluster ID. Replace `~/path/to/your-key-pair.pem` with the path to your key pair file. In this example, we use `~/emr-tutorial-key` as the path to your key pair.
 
 ```bash
 aws emr ssh --cluster-id j-1234ABCD5678 --key-pair-file ~/path/to/your-key-pair.pem
@@ -374,7 +374,7 @@ sudo cat /var/log/spark/spark-history-server.out
 **Troubleshooting**
 
 • **Connection timeout:** Verify that your security group allows SSH (port 22) from your IP
-• **Permission denied:** Ensure your key pair file has correct permissions. Replace "~/emr-tutorial-key.pem" with the path to your key pair file. In this example, we use "~/emr-tutorial-key" as the path to your key pair.
+• **Permission denied:** Ensure your key pair file has correct permissions. Replace `~/emr-tutorial-key.pem` with the path to your key pair file. In this example, we use `~/emr-tutorial-key` as the path to your key pair.
 ```
 chmod 400 ~/emr-tutorial-key.pem
 ```
@@ -387,19 +387,19 @@ When you're finished with the tutorial, clean up your resources to avoid incurri
 
 **Terminate the cluster**
 
-Terminate your EMR cluster. Replace "j-1234ABCD5678" with your cluster ID.
+Terminate your EMR cluster. Replace `j-1234ABCD5678` with your cluster ID.
 
 ```bash
 aws emr terminate-clusters --cluster-ids j-1234ABCD5678
 ```
 
-Check the termination status. Replace "j-1234ABCD5678" with your cluster ID.
+Check the termination status. Replace `j-1234ABCD5678` with your cluster ID.
 
 ```bash
 aws emr describe-cluster --cluster-id j-1234ABCD5678
 ```
 
-The cluster is terminated when its state changes to "TERMINATED". An example response is as follows: 
+The cluster is terminated when its state changes to `TERMINATED`. An example response is as follows: 
 
 ```json
 {
@@ -419,7 +419,7 @@ The cluster is terminated when its state changes to "TERMINATED". An example res
 
 **Delete S3 resources**
 
-Delete the contents of your S3 bucket. Replace "amzndemo-s3-demo-bucket" with the name of your Amazon S3 bucket.
+Delete the contents of your S3 bucket. Replace `amzndemo-s3-demo-bucket` with the name of your Amazon S3 bucket.
 
 ```bash
 aws s3 rm s3://amzndemo-s3-demo-bucket --recursive
diff --git a/tuts/040-qbusiness-ica/qbusiness-ica.md b/tuts/040-qbusiness-ica/qbusiness-ica.md
@@ -26,13 +26,13 @@ The total cost for running the resources in this tutorial for one hour is approx
 
 Amazon Q Business uses IAM Identity Center for user management. In this step, you'll check if you have an IAM Identity Center instance and create one if needed.
 
-First, check if you already have an IAM Identity Center instance. Replace "us-east-1" with the AWS Region where your IAM Identity Center instance is located.
+First, check if you already have an IAM Identity Center instance. Replace `us-east-1` with the AWS Region where your IAM Identity Center instance is located.
 
 ```bash
 aws sso-admin list-instances --region us-east-1 --query 'Instances[0].InstanceArn' --output text
 ```
 
-If the command returns "None" or an empty result, you need to create an IAM Identity Center instance. Replace "us-east-1" with the AWS Region where you want to create your IAM Identity Center instance.
+If the command returns `None` or an empty result, you need to create an IAM Identity Center instance. Replace `us-east-1` with the AWS Region where you want to create your IAM Identity Center instance.
 
 ```bash
 aws sso-admin create-instance --region us-east-1 --name "QBusinessIdentityCenter-abcd1234" --query 'InstanceArn' --output text
diff --git a/tuts/043-amazon-mq-gs/amazon-mq-gs.md b/tuts/043-amazon-mq-gs/amazon-mq-gs.md
@@ -92,7 +92,7 @@ The broker creation process takes about 15-20 minutes. You can check the status
 aws mq describe-broker --broker-id "$BROKER_ID" --query 'BrokerState' --output text
 ```
 
-Wait until the status shows "RUNNING" before proceeding to the next step.
+Wait until the status shows `RUNNING` before proceeding to the next step.
 
 ## Step 4: Get broker connection details
 
@@ -467,7 +467,7 @@ If you're having trouble connecting to your broker:
 
 1. **Check security group rules**: Ensure that the security group allows inbound connections from your IP address to the required ports.
 
-2. **Verify broker status**: Make sure the broker is in the "RUNNING" state.
+2. **Verify broker status**: Make sure the broker is in the `RUNNING` state.
 
 3. **Check network connectivity**: Ensure that your network allows outbound connections to the broker's endpoints.
 
diff --git a/tuts/044-amazon-managed-grafana-gs/amazon-managed-grafana-gs.md b/tuts/044-amazon-managed-grafana-gs/amazon-managed-grafana-gs.md
@@ -227,7 +227,7 @@ After creating the workspace, check its status to ensure it becomes active:
 aws grafana describe-workspace --workspace-id g-abcd1234
 ```
 
-Replace `g-abcd1234` with your workspace ID. The workspace status will initially be "CREATING". Wait until the status changes to "ACTIVE" before proceeding:
+Replace `g-abcd1234` with your workspace ID. The workspace status will initially be `CREATING`. Wait until the status changes to `ACTIVE` before proceeding:
 
 ```
 {
diff --git a/tuts/045-aws-iam-identity-center-gs/aws-iam-identity-center-gs.md b/tuts/045-aws-iam-identity-center-gs/aws-iam-identity-center-gs.md
@@ -156,7 +156,7 @@ aws sso-admin describe-account-assignment-creation-status \
   --account-assignment-creation-request-id "request-id-from-previous-command"
 ```
 
-Wait for the status to show "SUCCEEDED" before proceeding to the next step.
+Wait for the status to show `SUCCEEDED` before proceeding to the next step.
 
 **Provision permission set to account**
 
@@ -180,7 +180,7 @@ aws sso-admin describe-permission-set-provisioning-status \
   --provision-request-id "request-id-from-previous-command"
 ```
 
-Wait for the status to show "SUCCEEDED" before proceeding.
+Wait for the status to show `SUCCEEDED` before proceeding.
 
 ## Set up user access to applications
 
@@ -258,7 +258,7 @@ Here are some common issues you might encounter when setting up IAM Identity Cen
 
 **Issue**: Asynchronous operations don't complete as expected.
 
-**Solution**: Many IAM Identity Center operations are asynchronous, including account assignments and permission set provisioning. Always check the operation status using the appropriate describe command and wait for the status to show "SUCCEEDED" before proceeding to the next step.
+**Solution**: Many IAM Identity Center operations are asynchronous, including account assignments and permission set provisioning. Always check the operation status using the appropriate describe command and wait for the status to show `SUCCEEDED` before proceeding to the next step.
 
 **Issue**: Application creation fails with provider ARN errors.
 
diff --git a/tuts/052-aws-waf-gs/aws-waf-gs.md b/tuts/052-aws-waf-gs/aws-waf-gs.md
@@ -216,7 +216,7 @@ aws wafv2 associate-web-acl \
   --region us-east-1
 ```
 
-Replace "your-distribution-id" with the actual ID of your CloudFront distribution. This command associates your web ACL with the specified CloudFront distribution, enabling AWS WAF to inspect and filter requests to that distribution.
+Replace `your-distribution-id` with the actual ID of your CloudFront distribution. This command associates your web ACL with the specified CloudFront distribution, enabling AWS WAF to inspect and filter requests to that distribution.
 
 ## Configure logging
 
diff --git a/tuts/057-amazon-managed-streaming-for-apache-kafka-gs/amazon-managed-streaming-for-apache-kafka-gs.md b/tuts/057-amazon-managed-streaming-for-apache-kafka-gs/amazon-managed-streaming-for-apache-kafka-gs.md
diff --git a/tuts/059-amazon-datazone-gs/amazon-datazone-gs.md b/tuts/059-amazon-datazone-gs/amazon-datazone-gs.md
diff --git a/tuts/065-amazon-elasticache-gs/amazon-elasticache-gs.md b/tuts/065-amazon-elasticache-gs/amazon-elasticache-gs.md
diff --git a/tuts/074-amazon-textract-gs/amazon-textract-getting-started.md b/tuts/074-amazon-textract-gs/amazon-textract-getting-started.md
diff --git a/tuts/078-amazon-elastic-container-registry-gs/amazon-elastic-container-registry-gs.md b/tuts/078-amazon-elastic-container-registry-gs/amazon-elastic-container-registry-gs.md
diff --git a/tuts/085-amazon-ecs-service-connect/amazon-ecs-service-connect.md b/tuts/085-amazon-ecs-service-connect/amazon-ecs-service-connect.md

Original file line number	Diff line number	Diff line change
`@@ -75,7 +75,7 @@ Output:`
`75`	`75`	`}`
`76`	`76`	```
`77`	`77`
`78`		`-The response shows that your cluster has been created successfully and is in the "ACTIVE" status. You can now launch container instances and run tasks in this cluster.`
	`78`	+The response shows that your cluster has been created successfully and is in the `ACTIVE` status. You can now launch container instances and run tasks in this cluster.
`79`	`79`
`80`	`80`	`Verify cluster creation`
`81`	`81`