[Cache] ELI5: Simplify purge-cache docs

src/content/docs/cache/how-to/purge-cache/index.mdx

@@ -1,7 +1,7 @@
 ---
 title: Purge cache
 pcx_content_type: concept
-description: Remove cached content from Cloudflare edge servers.
+description: Remove cached content from Cloudflare data centers.
 products:
   - cache
 ---
@@ -42,7 +42,7 @@ Note that the thresholds for URLs are calculated using a moving average.
 
 ### Token bucket rate limiting
 
-Cloudflare uses token bucket rate limiting to limit the number of purge requests flowing through the system at any given time, ensuring a steady and manageable flow.
+Cloudflare uses token bucket rate limiting — a method that controls request flow using a fixed pool of "tokens" — to limit the number of purge requests flowing through the system at any given time.
 
 Each account tier has a defined request rate (for example, Free: 5 requests per minute, Business: 10 requests per second), and requests are only allowed if there are available tokens in the bucket. Tokens refill at a consistent rate, but each bucket has a maximum capacity (for example, Free: 25 tokens, Enterprise: 500 tokens), allowing short bursts of requests if tokens have accumulated.
 

src/content/docs/cache/how-to/purge-cache/purge-by-hostname.mdx

@@ -20,8 +20,7 @@ Purging by hostname means that all assets at URLs with a host that matches one o
 2. Under **Purge Cache**, select **Custom Purge**. The **Custom Purge** window appears.
 3. Under **Purge by**, select **Hostname**.
 4. Follow the syntax instructions:
-   * One hostname per line.
-   * Separated by commas.
+   * One hostname per line, or separated by commas.
    * You can purge up to 30 hostnames at a time.
 5. Enter the appropriate value(s) in the text field using the format shown in the example.
 6. Select **Purge**.
@@ -32,5 +31,5 @@ For information on rate limits, refer to the [Availability and limits](/cache/ho
 
 Purging by hostname deletes the resource, resulting in the `CF-Cache-Status` header being set to [`MISS`](/cache/concepts/cache-responses/#miss) for subsequent requests.
 
-If [tiered cache](/cache/how-to/tiered-cache/) is used, purging by hostname may return `EXPIRED`, as the lower tier tries to revalidate with the upper tier to reduce load on the latter.
+If [Tiered Cache](/cache/how-to/tiered-cache/) is used, purging by hostname may return `EXPIRED`, as the lower tier tries to revalidate with the upper tier to reduce load on the latter.
 Depending on whether the upper tier has the resource or not, and whether the end user is reaching the lower tier or the upper tier, `EXPIRED` or `MISS` are returned.

src/content/docs/cache/how-to/purge-cache/purge-by-single-file.mdx

@@ -26,7 +26,7 @@ A single-file purge performed through your Cloudflare dashboard does not clear o
   - `X-Rewrite-URL`
   - `Forwarded`
 
-You can purge objects with these characteristics using an API call to ([purge files by URL](/api/resources/cache/methods/purge/)). In the data/header section of the API call, you must include all headers and cache keys contained in the cached resource, along with their matching values.
+You can purge objects with these characteristics using an API call to [purge files by URL](/api/resources/cache/methods/purge/). In the data/header section of the API call, you must include all headers and cache keys contained in the cached resource, along with their matching values.
 
 :::caution
 Always use UTF-8 encoded URLs for single-file cache purges. Wildcards are not supported on single file purge, and you must use purge by hostname, prefix, or implement cache tags as an alternative solution.
@@ -39,7 +39,7 @@ Always use UTF-8 encoded URLs for single-file cache purges. Wildcards are not su
 2. Under **Purge Cache**, select **Custom Purge**. The **Custom Purge** window appears.
 3. Under **Purge by**, select **URL**.
 4. Enter the appropriate value(s) in the text field using the format shown in the example. Be aware that the host part of the URL is not case-sensitive, meaning it will always be converted to lowercase according to RFC standards. However, the path portion is case-sensitive. For example, `https://EXAMPLE.com/helloHI` would be treated as `https://example.com/helloHI`.
-5. Perform any additional instructions to complete the form.
+5. (Optional) Add any additional URLs to purge.
 6. Review your entries.
 7. Select **Purge**.
 

src/content/docs/cache/how-to/purge-cache/purge-by-tags.mdx

@@ -15,10 +15,10 @@ Cache-tag purging makes multi-file purging easier because you can instantly bulk
 
 ## General workflow for cache-tags
 
-1. Add tags to the `Cache-Tag` HTTP response header from your origin web server for your web content, such as pages, static assets, etc.
+1. Add tags to the `Cache-Tag` HTTP response header from your origin web server for your web content, such as pages and static assets.
 2. [Ensure your web traffic is proxied](/dns/proxy-status/) through Cloudflare.
 3. Cloudflare associates the tags in the `Cache-Tag` HTTP header with the content being cached.
-4. Use specific cache-tags to instantly purge your Cloudflare CDN cache of all content containing that cache-tag from your dashboard or [using our API](/api/resources/cache/methods/purge/).
+4. Use specific cache-tags to instantly purge your Cloudflare CDN cache of all content containing that cache-tag from your dashboard or [using the API](/api/resources/cache/methods/purge/).
 5. Cloudflare forces a [cache MISS](/cache/concepts/cache-responses/#miss) on content with the purged cache-tag.
 
 :::caution[Warning]
@@ -33,13 +33,13 @@ Be careful when purging. A cache MISS can cause execution delays by requiring a
 
 You add cache-tags to your web content in `Cache-Tag` HTTP response headers to allow the client and server to pass additional information in requests or responses. HTTP headers consist of a specific case-insensitive name followed by a colon `:` and the valid value, for example, `Cache-Tag:tag1,tag2,tag3`. Use commas to separate the tags when you want to use multiple cache-tags.
 
-When your content reaches our edge network, Cloudflare:
+When your content reaches the Cloudflare network, Cloudflare:
 
 * Removes the `Cache-Tag` HTTP header before sending the response to your website visitor or passing the response to a [Worker](/workers/). Your end users or Worker never see `Cache-Tag` HTTP headers on your Cloudflare-enabled website.
 * Removes whitespaces from the header and any before and after cache-tag names: `tag1`, `tag2` and `tag1,tag2` are considered the same.
 * Removes all repeated and trailing commas before applying cache-tags: `tag1,,,tag2` and `tag1,tag2` are considered the same.
 
-## A few things to remember
+## Cache-tag requirements
 
 * A single HTTP response can have more than one `Cache-Tag` HTTP header field.
 * The minimum length of a cache-tag is one byte.

src/content/docs/cache/how-to/purge-cache/purge-cache-key.mdx

@@ -12,7 +12,7 @@ sidebar:
 
 import { APIRequest } from "~/components";
 
-Instantly purge resources that use Cache Keys via the [Cloudflare API](/api/resources/cache/methods/purge/). If you use [Cloudflare's Purge by URL](/api/resources/cache/methods/purge/#purge-cached-content-by-url), include the headers and query strings that are in your custom Cache Key.
+Instantly purge resources that use custom [cache keys](/cache/how-to/cache-keys/) via the [Cloudflare API](/api/resources/cache/methods/purge/). Cache keys determine how Cloudflare identifies cached resources — custom keys let you cache different versions of a resource based on factors like device type, location, or language. If you use [Cloudflare's Purge by URL](/api/resources/cache/methods/purge/#purge-cached-content-by-url), include the headers and query strings that are in your custom Cache Key.
 
 Currently, it is not possible to purge a URL stored through Cache API that uses a custom cache key set by a Worker. Instead, use a [custom key created by Cache Rules](/cache/how-to/cache-rules/settings/#cache-key). Alternatively, purge your assets using purge everything, purge by tag, purge by host or purge by prefix.
 
@@ -22,7 +22,7 @@ To instantly purge by `device_type`, `geo`, or `lang` use `CF-Device-Type`, `CF-
 
 For a Cache Key based on device type, purge the asset by passing the `CF-Device-Type` header with the API purge request (valid headers include mobile, desktop, and tablet).
 
-Refer to the example API request below to instantly purge all mobile assets on the root webpage.
+The following example API request purges all mobile assets on the root webpage.
 
 <APIRequest
   path="/zones/{zone_id}/purge_cache"
@@ -60,7 +60,7 @@ Instantly purge resources for a location-based Cache Key by specifying the two-l
 
 ## Purge by language
 
-For a Cache Key based on language, purge the asset by passing the `accept-language` header. Refer to the example API request below to instantly purge all assets in Chinese (PRC).
+For a Cache Key based on language, purge the asset by passing the `accept-language` header. The following example API request purges all assets in Chinese (PRC).
 
 <APIRequest
   path="/zones/{zone_id}/purge_cache"

src/content/docs/cache/how-to/purge-cache/purge-everything.mdx

@@ -11,7 +11,7 @@ sidebar:
 
 import { DashButton } from "~/components"
 
-To maintain optimal site performance, Cloudflare strongly recommends using single-file (by URL) purging instead of a complete cache purge.
+To maintain optimal site performance, Cloudflare strongly recommends using single-file (by URL) purging instead of a complete cache purge. Use purge everything only when you need to clear all cached content at once, such as after a major site redesign or a security incident.
 
 Purging everything instantly clears all resources from your CDN cache in all Cloudflare data centers. Each new request for a purged resource returns to your origin server to validate the resource. If Cloudflare cannot validate the resource, Cloudflare fetches the latest version from the origin server and replaces the cached version. When a site with heavy traffic contains a lot of assets, requests to your origin server can increase substantially and result in slow site performance.
 

src/content/docs/cache/how-to/purge-cache/purge-zone-versions.mdx

@@ -11,9 +11,9 @@ sidebar:
 
 To purge zone versions via the Cloudflare API, follow these steps:
 
-## Step 1: Retrieve the environment ID
+## 1. Retrieve the environment ID
 
-First, retrieve your zone's environment ID by sending a request to the following API endpoint:
+Retrieve your zone's environment ID by sending a `GET` request to the following API endpoint:
 
 ```bash
 https://api.cloudflare.com/client/v4/zones/<zone_id>/environments
@@ -64,9 +64,9 @@ This API call will return a JSON response similar to the example below:
 }
 ```
 
-In this particular example, we have three environments: Production, Staging, and Development. You can find the environment ID in the `ref` field.
+This example includes three environments: Production, Staging, and Development. You can find the environment ID in the `ref` field.
 
-## Step 2: Purge cache per environment
+## 2. Purge cache per environment
 
 To purge the Production environment, use the general cache purge endpoint:
 

src/content/docs/cache/how-to/purge-cache/purge_by_prefix.mdx

@@ -11,7 +11,7 @@ sidebar:
 
 import { DashButton } from "~/components"
 
-You can instantly purge their cache by URL prefix or path separators in their URL. For an example URL like `https://www.example.com/foo/bar/baz/qux.jpg`, valid purge requests include:
+You can purge cached resources by URL prefix or path separator. For an example URL like `https://www.example.com/foo/bar/baz/qux.jpg`, valid purge requests include:
 
 * `www.example.com`
 * `www.example.com/foo`
@@ -51,7 +51,7 @@ If you have a [Transform Rule](/rules/transform/) in place that is modifying par
 
 Purging by prefix deletes the resource, causing `CF-Cache-Status` header to show [`MISS`](/cache/concepts/cache-responses/#miss) for the subsequent request.
 
-If [tiered cache](/cache/how-to/tiered-cache/) is used, purging by prefix may return `EXPIRED`, as the lower tier tries to revalidate with the upper tier to reduce load on the latter.
+If [Tiered Cache](/cache/how-to/tiered-cache/) is used, purging by prefix may return `EXPIRED`, as the lower tier tries to revalidate with the upper tier to reduce load on the latter.
 Depending on whether the upper tier has the resource or not, and whether the end user is reaching the lower tier or the upper tier, `EXPIRED` or `MISS` are returned.
 
 ## Limitations
@@ -61,7 +61,7 @@ There are several limitations regarding purge by prefix:
 * Path separators are limited to 31 for a prefix `(example.com/a/b/c/d/e/f/g/h/i/j/k/l/m…)`.
 * Purge requests are limited to 30 prefixes per request.
 * [Purge rate-limits apply](/api/resources/cache/methods/purge/).
-* URI query strings & fragments cannot purge by prefix:
+* URI query strings and fragments cannot purge by prefix:
   * `www.example.com/foo?a=b` (query string)
   * `www.example.com/foo#bar` (fragment)
 
@@ -79,7 +79,7 @@ Example: If you purge `foo.com/bar`, any asset that starts with `foo.com/bar` wi
 
 Using purge by prefix normalization, when a purge by prefix request comes into Cloudflare for a normalized URL path, the purge service respects the [URL normalization](/rules/normalization/) and purges the normalized URL.
 
-### How does URL Normalization work
+### URL normalization behavior
 
 Take the following website as an example: `https://cloudflare.com/انشاء-موقع-الكتروني/img_1.jpg`. The table below shows you how Cloudflare’s cache views these paths with [normalization on/off](/rules/normalization/).