Docs: rewrite the docs/README file

I originally wrote this file when we first added snippets testing
and a lot has changed. We've grown quite fond of the
`// TESTRESPONSE[s/foo/bar/]` construct, for example, but the docs
discouraged its use.

Relates to #18160

Author: nik9000

docs/README.asciidoc

@@ -4,24 +4,28 @@ Elasticsearch documentation build process.
 See: https://github.com/elastic/docs
 
 Snippets marked with `// CONSOLE` are automatically annotated with "VIEW IN
-CONSOLE" in the documentation and are automatically tested by the command
-`gradle :docs:check`. To test just the docs from a single page, use e.g.
-`gradle :docs:check -Dtests.method=*rollover*`.
+CONSOLE" and "COPY AS CURL" in the documentation and are automatically tested
+by the command `gradle :docs:check`. To test just the docs from a single page,
+use e.g. `gradle :docs:check -Dtests.method=*rollover*`.
 
-By default `// CONSOLE` snippet runs as its own isolated
-test. You can manipulate the test execution in the following ways:
+By default each `// CONSOLE` snippet runs as its own isolated test. You can
+manipulate the test execution in the following ways:
 
 * `// TEST`: Explicitly marks a snippet as a test. Snippets marked this way
-are tests even if they don't have `// CONSOLE`.
-  * `// TEST[s/foo/bar/]`: Replace `foo` with `bar` in the test. This should be
-  used sparingly because it makes the test "lie". Sometimes, though, you can use
-  it to make the tests more clear.
+are tests even if they don't have `// CONSOLE` but usually `// TEST` is used
+for its modifiers:
+  * `// TEST[s/foo/bar/]`: Replace `foo` with `bar` in the generated test. This
+  should be used sparingly because it makes the snippet "lie". Sometimes,
+  though, you can use it to make the snippet more clear more clear. Keep in
+  mind the that if there are multiple substitutions then they are applied in
+  the order that they are defined.
   * `// TEST[catch:foo]`: Used to expect errors in the requests. Replace `foo`
   with `request` to expect a 400 error, for example. If the snippet contains
   multiple requests then only the last request will expect the error.
   * `// TEST[continued]`: Continue the test started in the last snippet. Between
-  tests the nodes are cleaned: indexes are removed, etc. This will prevent that.
-  This is really useful when you have text and snippets that work together to
+  tests the nodes are cleaned: indexes are removed, etc. This prevents that
+  from happening between snippets because the two snippets are a single test.
+  This is most useful when you have text and snippets that work together to
   tell the story of some use case because it merges the snippets (and thus the
   use case) into one big test.
   * `// TEST[skip:reason]`: Skip this test. Replace `reason` with the actual
@@ -38,8 +42,11 @@ are tests even if they don't have `// CONSOLE`.
 * `// TESTRESPONSE`: Matches this snippet against the body of the response of
   the last test. If the response is JSON then order is ignored. If you add
   `// TEST[continued]` to the snippet after `// TESTRESPONSE` it will continue
-  in the same test, allowing you to interleve requests with responses to check.
-  * `// TESTRESPONSE[s/foo/bar/]`: Substitutions. See `// TEST[s/foo/bar]`.
+  in the same test, allowing you to interleave requests with responses to check.
+  * `// TESTRESPONSE[s/foo/bar/]`: Substitutions. See `// TEST[s/foo/bar]` for
+  how it works. These are much more common than `// TEST[s/foo/bar]` because
+  they are useful for eliding portions of the response that are not pertinent
+  to the documentation.
   * `// TESTRESPONSE[_cat]`: Add substitutions for testing `_cat` responses. Use
   this after all other substitutions so it doesn't make other substitutions
   difficult.