Apply suggestions from code review

Author: irvinebroque

src/content/docs/containers/examples/index.mdx

@@ -4,7 +4,7 @@ hideChildren: false
 pcx_content_type: navigation
 title: Examples
 sidebar:
-  order: 10
+  order: 3
 ---
 
 import { GlossaryTooltip, ListExamples } from "~/components";

src/content/docs/containers/get-started.mdx

@@ -17,49 +17,47 @@ This example Worker should give you a sense for simple Container use, and provid
 ### Ensure Docker is running locally
 
 In this guide, we will build and push a container image alongside your Worker code. By default, this process uses
-Docker to do so. You must have Docker running locally when you run `wrangler deploy`.
+[Docker](https://www.docker.com/) to do so. You must have Docker running locally when you run `wrangler deploy`. For most people, the best way to install Docker is to follow the [docs for installing Docker Desktop](https://docs.docker.com/desktop/).
 
-If Docker is running properly, the `docker info` command will successfully run. If Docker is not running,
+You can check that Docker is running properly by running the `docker info` command in your terminal. If Docker is running, the command will succeed. If Docker is not running,
 the `docker info` command will hang or return an error including the message "Cannot connect to the Docker daemon".
 
 {/* FUTURE CHANGE: Add some image you can use if you don't have Docker running. */}
 {/* FUTURE CHANGE: Link to docs on alternative build/push options */}
 
-## Deploy a Container to Workers
+## Deploy your first Container
 
-Now that your environment is set up, you can write your Worker.
 
-### Deploy from the Hello World Template
 
-Use [C3](/learning-paths/workers/get-started/c3-and-wrangler/#c3) to create and deploy a new Worker using the "Hello World Containers" template.
+Run the following command to create and deploy a new Worker with a container, from the starter template:
 
 ```sh
 npm create cloudflare@latest -- --template=cloudflare/templates/hello-world-containers
 ```
 
-Subsequent updates to the Worker or Container code can be deployed using Wrangler:
+When you want to deploy a code change to either the Worker or Container code, you can run the following command using [Wrangler CLI](/workers/wrangler/:
 
 <PackageManagers type="exec" pkg="wrangler" args="deploy" />
 
-When you run this command, several things happen:
+When you run `wrangler deploy`, the following things happen:
 
-- Wrangler builds your image using Docker.
-- Wrangler pushes your image to the Cloudchamber Image Registry, which is automatically
+- Wrangler builds your container image using Docker.
+- Wrangler pushes your image to a [Container Image Registry](/containers/image-management/) that is automatically
   integrated with your Cloudflare account.
-- Wrangler deploys your Worker, which includes setting up a "Container" for it to interact with.
+- Wrangler deploys your Worker, and configures Cloudflare's network to be ready to spawn instances of your container
 
 :::note
-The build and push usually take the longest on the first deploy. Future deploys
-will go faster by [reusing cached image layers](https://docs.docker.com/build/cache/).
+The build and push usually take the longest on the first deploy. Subsequent deploys
+are faster, because they [reuse cached image layers](https://docs.docker.com/build/cache/).
 :::
 
 After you deploy your Worker for the first time, you will need to wait several minutes until
 it is ready to receive requests. Unlike Workers, Containers take a few minutes to be provisioned.
 During this time, requests are sent to the Worker, but calls to the Container will error.
 
-### Check deploy status
+### Check deployment status
 
-After deploying, you can list containers in your accout with the following command:
+After deploying, run the following command to show a list of containers containers in your Cloudflare account, and their deployment status:
 
 <PackageManagers type="exec" pkg="wrangler" args="containers list" />
 
@@ -69,7 +67,7 @@ And see images deployed to the Cloudflare Registry with the following command:
 
 ### Make requests to Containers
 
-Now, open the URL for your worker. It should look something like `https://hello-containers.YOUR_ACCOUNT_NAME.workers.dev`.
+Now, open the URL for your Worker. It should look something like `https://hello-containers.YOUR_ACCOUNT_NAME.workers.dev`.
 
 If you make requests to the paths `/container/1` or `/container/2`, these requests are routed to specific containers.
 Each different path after "/container/" routes to a unique container.
@@ -78,17 +76,20 @@ If you make requests to `/lb`, you will load balanace requests to one of 3 conta
 
 You can confirm this behavior by reading the output of each request.
 
-## Understanding Durable Objects and Containers
+## Understanding the Code
+
+Now that you've deployed your first container, let's explain what is happening in your Worker's code, in your configuration file, in your container's code, and how requests are routed.
+## Each Container is backed by its own Durable Object
 
-Requests are initially handled by the Worker, then passed to container-enabled [Durable Objects](/durable-objects)
-that is defined by the [`Container` class](https://github.com/cloudflare/containers).
+Incoming requests are initially handled by the Worker, then passed to a container-enabled [Durable Object](/durable-objects).
+To simplify and reduce boilerplate code, Cloudflare provides a [`Container` class](https://github.com/cloudflare/containers) as part of the `@cloudflare/containers` NPM package.
 
 You don't have to be familiar with Durable Objects to use Containers, but it may be helpful
 to understand how the basics.
 
 Each Durable Object runs alongside an individual container instance, manages starting and stopping it, and
 can interact with the container through its ports. Containers will likely run near the Worker instance
-requesting them, but not necessarily. See ["How Locations are Selected"](/containers/platform-details/#how-are-locations-are-selected)
+requesting them, but not necessarily. Refer to ["How Locations are Selected"](/containers/platform-details/#how-are-locations-are-selected)
 for details.
 
 In a simple app, the Durable Object may just boot the container and proxy requests to it.
@@ -100,11 +101,10 @@ on container status changes, and more.
 See the [documentation for Durable Object container methods](/durable-objects/api/container/) and the
 [`Container` class repository](https://github.com/cloudflare/containers) for more details.
 
-## Understanding the Code
 
-### Worker Config
+### Configuration
 
-First, wrangler config sets up a container and a Durable Object that will run alongside it.
+Your [Wrangler configuration file](/workers/wrangler/configuration/) defines the configuration for both your Worker and your container:
 
 <WranglerConfig>
 
@@ -129,16 +129,16 @@ new_sqlite_classes = ["MyContainer"]
 Important points about this config:
 
 - `image` points to a Dockerfile or to a directory containing a Dockerfile.
-- `class_name` must be a Durable Object class name.
+- `class_name` must be a [Durable Object class name](/durable-objects/api/base/).
 - `max_instances` declares the maximum number of simultaneously running container instances
   that will run.
-- The Durable Object must use `new_sqlite_classes` not `new_classes`.
+- The Durable Object must use [`new_sqlite_classes`](/durable-objects/best-practices/access-durable-objects-storage/#create-sqlite-backed-durable-object-class) not `new_classes`.
 
 ### The Container Image
 
-The container image itself has to run on the `linux/amd64` architecture, but aside from that has few limitations.
+Your container image must be able to run on the `linux/amd64` architecture, but aside from that, has few limitations.
 
-In this case, it is a simple Golang server that responds to requests on port 8080 using
+In the example you just deployed, it is a simple Golang server that responds to requests on port 8080 using
 the `MESSAGE` environment variable that will be set in the Worker and an [auto-generated
 environment variable](/containers/platform-details/#environment-variables) `CLOUDFLARE_DEPLOYMENT_ID.`
 
@@ -152,7 +152,7 @@ func handler(w http.ResponseWriter, r *http.Request) {
 ```
 
 :::note
-After deploying the example code, feel free to replace the provided image with one of your own.
+After deploying the example code, to deploy a different image, you can replace the provided image with one of your own.
 :::
 
 ### Worker code
@@ -195,7 +195,7 @@ See the [Container class documentation](/containers/container-package) for more
 
 #### Routing to Containers
 
-In the Worker's main `fetch` handler, Containers are launched in one of two ways:
+When a request enters Cloudflare, your Worker's [`fetch` handler](/workers/runtime-apis/handlers/fetch/) is invoked. This is the code that handles the incoming request. The fetch handler in the example code, launches containers in two ways, on different routes:
 
 - Making requests to `/container/` passes requests to a new container for
   each path. This is done by spinning up a new Container instance. You may note
@@ -211,8 +211,8 @@ In the Worker's main `fetch` handler, Containers are launched in one of two ways
   ```
 
 - Making requests to `/lb` will load balance requests across several containers.
-  This uses a simple `getRandom` helper method currently, which picks an ID at random
-  from a set number (in this case 3), then routes to that Container instance.
+  This uses a simple `getRandom` helper method, which picks an ID at random
+  from a set number (in this case 3), then routes to that Container instance. You can replace this with any routing or load balancing logic you choose to implement:
 
   ```js
   if (pathname.startsWith("/lb")) {
@@ -236,9 +236,7 @@ This allows for multiple ways of using Containers:
 Currently, routing requests to one of many interchangeable Container instances is accomplished
 with the `getRandom` helper.
 
-This is a temporary solution until first-party support for utilization-aware autoscaling
-and latency-aware load balancing is added to Cloudflare Containers. We plan to add this
-in the coming months.
+This is temporary — we plan to add native support for latency-aware autoscaling and load balancing in the coming months.
 :::
 
 ## View Containers in your Dashboard

src/content/docs/containers/local-dev.mdx

@@ -1,11 +1,11 @@
 ---
 pcx_content_type: reference
-title: Local Dev
+title: Local Development
 sidebar:
   order: 3
 ---
 
-## Local Development
+You can run both your container and your Worker locally, without additional configuration, by running [`npx wrangler dev`](/workers/wrangler/commands/#dev) in your project's directory.
 
 To develop Container-enabled Workers locally, you will need to first ensure that a
 Docker compatible CLI tool is installed. For instance, you can use [Docker Desktop](https://docs.docker.com/desktop/)
@@ -26,22 +26,21 @@ local images are not removed, so that they can be reused in subsequent calls to
 `wrangler dev` or `wrangler deploy`.
 
 :::note
-If your Worker app creates many container instances, you may hit local limits
-on concurrent containers.
+If your Worker app creates many container instances, your local machine may not be able to run as many containers concurrently as is possible when you deploy to Cloudflare.
 
 Additionally, if you regularly rebuild containers locally, you may want to clear
 out old container images (using `docker image prune` or similar) to reduce disk used.
 :::
 
 ## Iterating on Container code
 
-When using `wrangler dev`, standard Worker code is automatically reloaded by wrangler you save a change,
+When you use `wrangler dev`, your Worker's code is automatically reloaded by Wrangler each time you save a change,
 but code running within the container is not.
 
-If you wish to rebuild your container with new code changes, you can hit the `[r]` key on your keyboard, and a
-rebuild will be triggered. Instances will be restarted with the new images.
+To rebuild your container with new code changes, you can hit the `[r]` key on your keyboard, which
+triggers a rebuild. Container instances will then be restarted with the newly built images.
 
-You may prefer to set up your code watchers and reloading mechanisms, or mount a local directory
+You may prefer to set up your own code watchers and reloading mechanisms, or mount a local directory
 into the local container images to sync code changes. This can be done, but there is no built-in
 mechanism for doing so in Wrangler, and best-practices will depend on the languages and frameworks
 you are using in your container code.

src/content/docs/containers/platform-details.mdx

@@ -1,6 +1,6 @@
 ---
 pcx_content_type: navigation
-title: Platform Details
+title: Platform
 sidebar:
   order: 2
   group:
@@ -9,39 +9,36 @@ sidebar:
 
 import { WranglerConfig } from "~/components";
 
-This page containers general details about the Containers platform.
 
 ## Instance Types
 
 The memory, vCPU, and disk space for Containers are set through predefined instance types.
-There are currently three instance types available for Containers users by default:
+Three instance types are currently available:
 
 | Instance Type | Memory  | vCPU | Disk |
 | ------------- | ------- | ---- | ---- |
 | dev           | 256 MiB | 1/16 | 2 GB |
 | basic         | 1 GiB   | 1/4  | 4 GB |
 | standard      | 4 GiB   | 1/2  | 4 GB |
 
-These are specified using the `instance_type` property in wrangler config.
+These are specified using the [`instance_type` property](/workers/wrangler/configuration/#containers) in your Worker's Wrangler configuration file. Looking for larger instances? [Give us feedback here](/containers/beta-info/#feedback-wanted) and tell us what size instances you need, and what you want to use them for.
 
 ## Limits
 
-Containers limits are currently set per account. You may have higher
-limits on your account if configured as such.
 
-The default limits during the initial beta phase are:
+While in open beta, the following limits are currently in effect:
 
 | Feature                                           | Workers Paid |
 | ------------------------------------------------- | ------------ |
-| GB Memory for concurrent live Container instances | 40GB [^1]    |
-| vCPU for concurrent live Container instances      | 20 [^1]      |
-| GB Disk for concurrent live Container instances   | 100GB [^1]   |
+| GB Memory for all concurrent live Container instances | 40GB [^1]    |
+| vCPU for all concurrent live Container instances      | 20 [^1]      |
+| GB Disk for all concurrent live Container instances   | 100GB [^1]   |
 | Image size                                        | 2 GB         |
-| Total image storage for account                   | 50 GB [^2]   |
+| Total image storage per account                   | 50 GB [^2]   |
 
 [^1]: This limit will be raised as we continue the beta.
 
-[^2]: Delete images with `wrangler containers delete` to free up space. Note that reverted Workers may then break.
+[^2]: Delete container images with `wrangler containers delete` to free up space. Note that if you delete a container image and then [roll back](/workers/configuration/versions-and-deployments/rollbacks/) your Worker to a previous version, this version may no longer work.
 
 ## Environment variables