Apply suggestions from jensens code review

Co-authored-by: Jens W. Klein <[email protected]>

Author: 2 people

docs/deployment/caching/composite-views.md

@@ -1,19 +1,15 @@
 # Composite views
 
-A `composite view` is just a general term for most page views you see when you visit a Plone site.
+The term *composite view* refers to most of the page views that are visible on a Plone website, including views of content listings, content folders, many template views, and rarely also specific content items. 
 
-It includes all content item views, content folder views, and many template views.
+These views can be difficult to manage because of the various changes that may affect the final composite view. As a result, composite views are typically challenging to remove reliably from caching proxies. 
+To address this issue, the default caching profiles set headers that expire the cache immediately, which is known as *weak caching*.
 
-For our purposes, the distinguishing characteristic of composite views is the difficulty inherent in keeping track of all changes that might affect the final composited view.
+However, the inline resources linked to from the composite view, such as CSS, JavaScript, and images, can typically be cached effectively in proxies. As a result, caching proxies can improve the overall speed of most composite views, even if the page itself is not cached.
 
-Because of the difficulty of dependency tracking, composite views are often notoriously difficult to purge reliably from caching proxies so the default caching profiles set headers which expire the cache immediately (i.e. *weak caching*).
+For relatively stable composite views or views where some staleness is tolerable, it may be tempting to switch from *weak caching* to *terse caching* with the s-maxage expiration value set 60 seconds by default. 
 
-However, most of the inline resources linked to from the composite view (css, javascript, images, etc.) can be cached very well in proxy so the overall speed of most composite views will always be better with a caching proxy in front despite the page itself not being cached.
-
-For relatively stable composite views or for those views for which you can tolerate some potential staleness, you might be tempted to try switching from *weak caching* to *moderate caching* with the `s-maxage` expiration value set to some tolerable value but first make sure you understand the issues regarding "split view" caching (see below).
-
-A way to speedup a site with lots of composite view is to use "Terse" caching.
-
-It caches a page for just a small time (be default 10s in browser and 60s in the caching proxy).
-
-Thus the content is almost up to date, but on high load visitors are getting pages served from the cache.
+To increase the speed of a site that contains many composite views, a technique called "Terse" caching can be used. 
+Terse caching involves caching a page for a brief period, typically 10 seconds in the browser and 60 seconds in the caching proxy. 
+This ensures that the content is almost up to date, but during periods of high traffic, visitors may receive pages served from the cache.
+This technique can actually speed up a site during periods of high traffic compared to low traffic since, during high traffic, the request can be served from the cache instead of having to go to the backend.

docs/deployment/caching/enable.md

@@ -29,7 +29,7 @@ In the Caching control panel, the tab `Change settings` is selected and inside o
 :alt: Caching Control Panel with caching disabled
 ```
 
-To enable caching, just click the checkbox:
+To enable caching, click the checkbox:
 
 ```{image} /_static/caching/ControlPanel-03.png
 :alt: Caching Control Panel with caching enabled

docs/deployment/caching/etags.md

@@ -11,15 +11,14 @@ myst:
 
 # ETags
 
-ETags are used in to check whether pages need to be re-calculated or can be served from cache.
-An ETag is simply a string. Under `plone.app.caching`, it is a string of tokens separated by pipe characters.
-The tokens hold values such as a user id, the current skin name, or a counter indicating how many objects have been added to the site.
-The idea is that the browser sends a request with the ETag included in an `If-None-Match` header.
-Plone can then quickly calculate the current ETag for the requested resource.
-If the ETag is the same, Plone can reply with `304 NOT MODIFIED` response, telling the browser to use its cached copy.
-Otherwise, Plone renders the page and returns it as normal.
+ETags are used in to determine whether pages need to be re-calculated or can be served from cache.
+An ETag generated by `plone.app.caching' is a string of tokens separated by pipe characters that hold values like a user ID, the current skin name, or a counter indicating how many objects have been added to the site.
+This technique is used to quickly calculate the current ETag for the requested resource. 
+The browser sends a request with the ETag included in an `If-None-Match` header, and if the ETag is the same, Plone responds with a 304 NOT MODIFIED message, indicating that the browser should use its cached copy. 
+If the ETag is different, Plone renders the page and returns it as normal.
 
-Many caching operations use ETags. The tokens to include are typically listed in an `etags` tuple in the operation's options.
+Many caching operations use ETags. 
+The tokens to include are typically listed in an `etags` tuple in the operation's options.
 
 ## Default tokens
 
@@ -43,7 +42,8 @@ It is possible to provide additional tokens by registering an `IETagValue` adapt
 
 This should be a named adapter on the published object (typically a view, file resource or Zope page template object) and request, with a unique name.
 
-The name is used to look up the component. Thus, you can also override one of the tokens above for a particular type of context or request (e.g. via a browser layer), by registering a more specific adapter with the same name.
+The name is used to look up the component. 
+Thus, you can also override one of the tokens above for a particular type of context or request (e.g. via a browser layer), by registering a more specific adapter with the same name.
 
 As an example, here is the `language` adapter:
 

docs/deployment/caching/index.md

@@ -13,15 +13,20 @@ myst:
 
 ## Overview
 
-HTTP caching is a technique used to speed up the delivery of web content by storing previously requested resources (such as images, scripts, and stylesheets) in a cache. When a user requests a resource, the cache can serve the resource directly from its storage, rather than having to fetch it from the original source.
+HTTP caching is a technique used to speed up the delivery of web content by storing previously requested resources (such as images, scripts, and stylesheets) in a cache. 
+When a user requests a resource, the cache can serve the resource directly from its storage, rather than having to fetch it from the original source.
 
-It is possible to use a web accelerator, like {term}`Varnish` or {term}`Squid`, to implement HTTP caching in your own premises. The usual setup will have the web accelerator installed between Plone and the Internet, and when a request is made to the site the web accelerator will intercept the request and check to see if it has a cached copy of the requested resource. If a cached copy is found, the accelerator will serve the cached copy directly to the client, otherwise it will make a request to the backend Plone server and then store a copy on the content in its local cache.
+It is possible to use a web accelerator, like {term}`Varnish` to implement HTTP caching in your own premises. 
+The usual setup will have the web accelerator installed between Plone and the Internet, and when a request is made to the site the web accelerator will intercept the request and check to see if it has a cached copy of the requested resource. 
+If a cached copy is found, the accelerator will serve the cached copy directly to the client, otherwise it will make a request to the backend Plone server and then store a copy on the content in its local cache.
 
-A Content Delivery Network (CDN) can also be used to implement the HTTP caching and speed up the delivery of web content. A CDN is a network of servers located in multiple geographic regions that work together to deliver web content to users more quickly and efficiently. When a user requests a resource from a website that is using a CDN, the request is routed to the nearest server in the CDN, rather than having to travel all the way to the website's origin server.
+HTTP caching and the speed of delivering web content can be improved using a Content Delivery Network (CDN).
+A CDN is a network of servers located in various geographic regions that work together to deliver web content to users quickly and efficiently. 
+When a user requests a resource from a website that uses a CDN, the request is directed to the closest server in the CDN, rather than having to travel all the way to the website's origin server.
 
 ## Plone support
 
-Plone, since version 4.1, ships with a powerful and extensible `HTTP` and `In-Memory` cache support, implemented by the package `plone.app.caching`.
+Plone ships with a powerful and extensible `HTTP` and `In-Memory` cache support, implemented by the package `plone.app.caching`.
 
 
 ```{toctree}

docs/deployment/caching/profiles.md

@@ -20,17 +20,16 @@ The *Import settings* tab of the control panel allows you to import these cachin
 
 ## Default caching profiles
 
-`plone.app.caching` includes three default caching profiles.
-
-Two of these  profiles encapsulate the cache settings that are known to work well with a typical default Plone installation:
+`plone.app.caching` includes two default caching profiles.
+These  profiles encapsulate the cache settings that are known to work well with a typical default Plone installation:
 
 ### Without caching proxy
 
 Settings useful for setups without a caching proxy.
 
 ### With caching proxy
 
-Settings useful for setups with a caching proxy such as Squid or Varnish.
+Settings useful for setups with a caching proxy such Varnish or a CDN.
 The only difference from the "without caching proxy" profile are some settings to enable proxy caching of files/images in content space and content feeds.
 
 ## Custom caching profiles

docs/deployment/caching/proxies.md

@@ -32,7 +32,7 @@ There are four general strategies for dealing with this:
 
 Since resources are cached in the proxy based on their URL, you can "invalidate" the cached copy by changing an item's URL when it is updated.
 
-This is the approach taken by Plone's resource management: In production mode, the links that are inserted into Plone's content pages for resource managed by Plone  contain a hash-based token, which changes when the main bundle file changes.
+This is the approach taken by Plone's resource management: Links that are inserted into Plone's content pages for resources managed by Plone  contain a hash-based token, which changes when the main bundle file changes.
 
 This approach has the benefit of also being able to "invalidate" content stored in a user's browser cache.
 
@@ -46,7 +46,7 @@ This is sometimes an acceptable policy for high-volume sites where most users do
 
 Given the proxy has cached a resource at `/logo.jpg`, and that object is modified.
 
-Then a PURGE request could be sent to the proxy (originating from Zope, not the client) with the same path to force the proxy to fetch a new version the next time the item is requested.
+Then a PURGE request could be sent to the proxy (originating from the backend, not the browser) with the same path to force the proxy to fetch a new version the next time the item is requested.
 
 ### Avoid caching
 
@@ -63,7 +63,7 @@ Nevertheless a "terse" policy allows caching for just a few seconds of all pages
 
 ## Purging a caching proxy
 
-Synchronous and asynchronous purging is enabled via [plone.cachepurging](https://pypi.org/project/plone.cachepurging).
+Synchronous and asynchronous purging is enabled via [plone.cachepurging](https://pypi.org/project/plone.cachepurging), which is installed as a dependency of `plone.app.caching`.
 
 In the control panel, you can configure the use of a proxy via various options, such as: