doc edits

CONTRIBUTING.md

@@ -62,6 +62,8 @@ To serve the site locally:
 mkdocs serve
 ```
 
+NOTE: on some OS's you might need to cd into your local clone and run 'git submodule init' and 'git submodule update' to get all of the plugins working properly.
+
 > **WARNING:** Note that the multi-repo site maybe quite slow during the
 > first build and then during the rebuilds.
 > You can disable it for local development just by commenting out the plugin section in `mkdocs.yml`

_site/docs/README.md

@@ -9,7 +9,7 @@ description: >
 WireMock is a popular open-source tool for API mock testing,
 with over 5 million downloads per month.
 It can help you to create stable test and
-development environments, isolate yourself from flakey 3rd parties and
+development environments, isolate you from flakey 3rd parties, and
 simulate APIs that don't exist yet.
 
 <style>

_site/docs/configuration.md

@@ -1,10 +1,11 @@
 ---
-description: Configuring WireMock progammatically in Java.
+description: progammatic config in Java.
 ---
 
 # Configuring WireMock in Java
+// consider adding an introductory sentence here
 
-Both `WireMockServer` and the `WireMockRule` take a configuration builder as the parameter to their constructor e.g.
+Both `WireMockServer` and the `WireMockRule` take a configuration builder as the parameter to their constructor like this example:
 
 ```java
 import static com.github.tomakehurst.wiremock.core.WireMockConfiguration.options;
@@ -15,7 +16,7 @@ WireMockServer wm = new WireMockServer(options().port(2345));
 WireMockRule wm = new WireMockRule(options().port(2345));
 ```
 
-Every option has a sensible default, so only options that you require an override for should be specified.
+Every option has a sensible default, so only options for which you require an override should be specified.
 
 ## Network ports and binding
 
@@ -90,12 +91,9 @@ WireMock can accept HTTPS connections from clients, require a client to present
 
 WireMock uses the trust store for three purposes:
 
-1. As a server, when requiring client auth, WireMock will trust the client if it
-   presents a public certificate in this trust store
-2. As a proxy, WireMock will use the private key & certificate in this key store
-   to authenticate its http client with target servers that require client auth
-3. As a proxy, WireMock will trust a target server if it presents a public
-   certificate in this trust store
+- As a server, when requiring client auth, WireMock will trust the client if it presents a public certificate in this trust store.
+- As a proxy, WireMock will use the private key & certificate in this key store to authenticate its http client with target servers that require client auth.
+- As a proxy, WireMock will trust a target server if it presents a public certificate in this trust store.
 
 ## Proxy settings
 
@@ -133,7 +131,7 @@ WireMock uses the trust store for three purposes:
 
 ## File locations
 
-WireMock, when started programmatically, will default to `src/test/resources` as a filesystem root if not configured otherwise.
+If not configured otherwise, WireMock defaults to the filesystem root `src/test/resources` upon startup.
 
 ```java
 // Set the root of the filesystem WireMock will look under for files and mappings
@@ -145,7 +143,7 @@ WireMock, when started programmatically, will default to `src/test/resources` as
 
 ## Request journal
 
-The request journal records requests received by WireMock. It is required by the verification features, so these will throw errors if it is disabled.
+ Wiremock contains a request journal that records all requests it receives. The verification features require this, and will throw errors if it is disabled.
 
 ```java
 // Do not record received requests. Typically needed during load testing to avoid JVM heap exhaustion.
@@ -183,9 +181,9 @@ For details see [Extending WireMock](./extending-wiremock.md).
 
 ## Transfer encoding
 
-By default WireMock will send all responses chunk encoded, meaning with a `Transfer-Encoding: chunked` header present and no `Content-Length` header.
+By default WireMock sends all responses chunk encoded, which means it has a `Transfer-Encoding: chunked` header present and no `Content-Length` header.
 
-This behaviour can be modified by setting a chunked encoding policy e.g.
+You can modify the encoding policy:
 
 ```java
 .useChunkedTransferEncoding(Options.ChunkedEncodingPolicy.BODY_FILE)
@@ -209,25 +207,23 @@ To enable automatic sending of CORS headers on stub responses, do the following:
 
 ## Limiting logged response body size
 
-By default, response bodies will be recorded in the journal in their entirety. This can result in out of memory errors when very large bodies are served so WireMock
-provides an option to limit the number of bytes of response bodies retained (truncating any that are larger).
+By default, the journal records each entire response body. To prevent out-of-memory errors when working with large response bodies, you can set a limit, in bytes, to the response body size, with the result that WireMock truncates the larger ones upon saving.
 
 ```java
 .maxLoggedResponseSize(100000) // bytes
 ```
 
 ## Preventing proxying to and recording from specific target addresses
 
-As a security measure WireMock can be configured to only permit proxying (and therefore recording) to certain addresses.
-This is achieved via a list of allowed address rules and a list of denied address rules, where the allowed list is evaluated first.
+For security, you can set limits on prxying from WireMock, using using rules lists that specify allowed and denied addresses. WireMock evaluates the allowed list first.
 
 Each rule can be one of the following:
 
 * A single IP address
-* An IP address range in the e.g. `10.1.1.1-10.2.2.2`
-* A hostname wildcard e.g. `dev-*.example.com`
+* An IP address range, as in `10.1.1.1-10.2.2.2`
+* A hostname wildcard, as in `dev-*.example.com`
 
-The ruleset is built and applied as follows:
+The ruleset is built and applied as in the following example:
 
 ```java
 .limitProxyTargets(NetworkAddressRules.builder()
@@ -240,7 +236,7 @@ The ruleset is built and applied as follows:
 
 ## Filename template
 
-WireMock can set up specific filename template format based on stub information.
+WireMock can set up specific filename template formats based on stub information.
 The main rule for set up specify stub metadata information in handlebar format.
 For instance for endpoint `PUT /hosts/{id}` and format
 {% raw %} `{{{method}}}-{{{request.url}}}.json`{% endraw %}
@@ -259,21 +255,20 @@ Note: starting from [3.0.0-beta-8](https://github.com/wiremock/wiremock/releases
 
 ## Listening for raw traffic
 
-If you would like to observe raw HTTP traffic to and from Jetty
-for debugging purposes you can use a `WiremockNetworkTrafficListener`.
+When debugging, you can observe raw HTTP traffic to and from Jetty
+ with a `WiremockNetworkTrafficListener`.
+
+ !!! Warning ""
+
+   Using WireMock's request listener extension points in some cases do not show some  alterations that Jetty can make, in the response from Wiremock, before sending it to the client. For example, if you set it to append a --gzip postfix to the ETag response header for gzipped responses, it does not show.
+
 
-One scenario where it can be useful is where Jetty
-alters the response from Wiremock before sending it to the client.
-(An example of that is where Jetty appends a --gzip postfix to the ETag response header
-if the response is gzipped.)
-Using WireMock's request listener extension points in this case would not show those alterations.
 
 To output all raw traffic to console use `ConsoleNotifyingWiremockNetworkTrafficListener`, for example:
 
 ```java
 .networkTrafficListener(new ConsoleNotifyingWiremockNetworkTrafficListener()));
 ```
 
-If you would like to collect the traffic
-and for example add it to your acceptance test's output,
+To collect raw traffic for other purposes, like adding to your acceptance test's output,
 you can use the `CollectingNetworkTrafficListener`.

_site/docs/download-and-installation.md

@@ -1,18 +1,19 @@
 ---
 description: >
-    WireMock is available as a standalone service for Docker or Java,
-    Java library, NPM package or SaaS.
-    Learn how to download and install WireMock.
+    download and install WireMock.
 ---
 
 # Download and Installation
 
+WireMock is available as a standalone service for Docker or Java, Java library, NPM package, or SaaS.
+
 ## Download options
 
-WireMock Java is distributed in two flavours - a standard JAR containing just WireMock, and a standalone uber JAR containing
-WireMock plus all its dependencies.
+WireMock ditributes Java packages in two flavours:
+- a standard JAR containing just WireMock.
+- a standalone uber JAR containing WireMock plus all its dependencies.
 
-Most of the standalone JAR's dependencies are shaded i.e. they are hidden in alternative packages. This allows WireMock to be used in projects with
+Most of the standalone JAR's dependencies are shaded--they are hidden in alternative packages. This allows WireMock to be used in projects with
 conflicting versions of its dependencies. The standalone JAR is also runnable (see [Running as a Standalone Process](./running-standalone.md)).
 
 ## Standalone Service

_site/docs/extending-wiremock.md

@@ -1,15 +1,15 @@
 ---
 description: >
-  How to create new WireMock extensions in your code,
-  and how to create and package redistributable extensions.
+  creating and sharing WireMock extensions.
 ---
 
 # Extending WireMock
 
-WireMock can be customised via a variety of extension points.
-You can register the extension programmatically via its class name, class or an instance.
+You can customise WireMock using a variety of extension points. You can create, package, and share reusable extensions.
 
-Each extension point is defined by an interface that extends from `Extension` and extension implementations are loaded at startup time.
+You have the option of registering extensions programmatically using the class name, class, or an instance.
+
+An interface defines each extension point, extendibg from `Extension`. Extension implementations load at startup time.
 
 At present, the following extension interfaces are available:
 * `RequestFilterV2`/`AdminRequestFilterV2`/`StubRequestFilterV2`: Intercept requests, modifying them or taking alternative actions based on their content.
@@ -28,8 +28,8 @@ The interfaces in this list ending with `V2` supercede deprecated equivalents wi
 
 ## Registering Extensions
 
-You can directly register the extension programmatically via its class name,
-class or an instance:
+You can directly register the extension programmatically using its class name,
+class, or an instance:
 
 ```java
 new WireMockServer(wireMockConfig()
@@ -72,14 +72,14 @@ Services currently available to extension factories are:
 
 ## Extension registration via service loading
 
-Extensions that are packaged with the relevant [Java service loader framework](https://docs.oracle.com/javase/8/docs/api/java/util/ServiceLoader.html) metadata
-will be loaded automatically if they are placed on the classpath.
+Iif they are placed on the classpath, extensions that are packaged with the relevant [Java service loader framework](https://docs.oracle.com/javase/8/docs/api/java/util/ServiceLoader.html) metadata
+will load automatically.
 
-See [https://github.com/wiremock/wiremock/tree/master/test-extension](https://github.com/wiremock/wiremock/tree/master/test-extension) for an example of such an extension.
+For an example of such an extension, see [https://github.com/wiremock/wiremock/tree/master/test-extension](https://github.com/wiremock/wiremock/tree/master/test-extension).
 
 ## Attaching sub-events during request processing
 
-Sub-events are a used to report interesting/useful information during request processing. WireMock attaches the diff report generated when a request is not matched as a sub-event, and custom extension can exploit this approach to surface e.g. diagnostic and validation data in the serve event log, where it can be retrieved later via the API or exported to monitoring/observability tools via listeners.
+You can make use of sub-events to report interesting/useful information during request processing. WireMock attaches the diff report generated when a request is not matched as a sub-event, and custom extension can exploit this approach to surface e.g. diagnostic and validation data in the serve event log, where it can be retrieved later via the API or exported to monitoring/observability tools via listeners.
 
 
 Several types of extension act on WireMock's request processing: `RequestFilterV2` (and its stub/admin sub-interfaces), `ResponseDefinitionTransformer`, `ResponseTransformer` and `ServeEventListener`.
@@ -93,4 +93,4 @@ serveEvent.appendSubEvent(
 );
 ```
 
-The second parameter to `appendSubEvent()` can be a Map or object containing any data required.
+The second parameter to `appendSubEvent()` can be a Map or object containing any data required.

_site/docs/faq.md

@@ -5,27 +5,26 @@ description: >
 
 # Frequently Asked Questions
 
-Here, you can find information about what API mocking and WireMock are, as well as recommendations and best practices for different challenges in various areas of WireMock.
+In this FAQ, you can find information about what API mocking and WireMock are, along with recommendations and best practices for different challenges in various areas of WireMock.
 
 ## API mocking and WireMock as a service
 
 ### What is WireMock?
 
-WireMock is a free API mocking tool that can be run as a standalone server, or in a hosted version via the [WireMock Cloud](https://wiremock.io/) managed service.
+WireMock is a free API mocking tool that you can run as a standalone server, or in a hosted version via the [WireMock Cloud](https://wiremock.io/) managed service.
 
 ### What is API mocking?
 
-API mocking involves creating a simple simulation of an API, accepting the same types of request and returning identically structured responses as the real thing,
-enabling fast and reliable development and testing.
+API mocking involves enabling fast and reliable development and testing by creating a simple simulation of an API and using it to accept requests and return responses that are identically structured to those used in the real API. 
 
 ### When do you need to mock APIs?
 
-API mocking is typically used during development and testing as it allows you to build your app without worrying about 3rd party APIs or sandboxes breaking.
-It can also be used to rapidly prototype APIs that don’t exist yet.
+Because it allows you to focus on building your app without worrying about 3rd party APIs or sandboxes breaking, API mocking is typically used during development and testing. 
+Another important use is rapid prototyping of APIs that don’t yet exist.
 
 ### How do you create an API mock?
 
-WireMock supports several approaches for creating mock APIs - in code, via its REST API, as JSON files and by recording HTTP traffic proxied to another destination.
+WireMock supports several approaches for creating mock APIs--in code, via its REST API, as JSON files, and by recording HTTP traffic proxied to another destination.
 
 ### What makes WireMock unique?
 
@@ -44,9 +43,9 @@ WireMock is completely free under the Apache 2.0 license.
 
 ## Technical questions
 
-### How to manage many mocks across different use cases and teams?
+### How do I manage many mocks across different use cases and teams?
 
-This question is valid especially when it is getting difficult to keep track of what test case(s) a particular mock was meant for.
+This question tends to arise at the point when it gets difficult to keep track of the intended test case(s) for which specific mocks were built.
 
 #### Potential solutions
 - Create your stubs (or most of them at least) in the test cases themselves, then [reset them](./stubbing.md#reset) each time.

_site/docs/getting-started.md

@@ -1,6 +1,6 @@
 ---
 description: >
-    How to get started with WireMock?
+    How to get started with WireMock
     This page provides links to WireMock tutorials and other entry materials
 ---