diff --git a/docs/README.asciidoc b/docs/README.asciidoc
index 766aeae0c5d..13a07e92d68 100644
--- a/docs/README.asciidoc
+++ b/docs/README.asciidoc
@@ -8,7 +8,8 @@ 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*"`.
 
-NOTE: If you have an elasticsearch-extra folder alongside your elasticsearch folder, you must temporarily rename it when you are testing 6.3 or later branches. 
+NOTE: If you have an elasticsearch-extra folder alongside your elasticsearch
+folder, you must temporarily rename it when you are testing 6.3 or later branches.
 
 By default each `// CONSOLE` snippet runs as its own isolated test. You can
 manipulate the test execution in the following ways:
@@ -36,7 +37,8 @@ for its modifiers:
   reason why the test shouldn't be run.
   * `// TEST[setup:name]`: Run some setup code before running the snippet. This
   is useful for creating and populating indexes used in the snippet. The setup
-  code is defined in `docs/build.gradle`.
+  code is defined in `docs/build.gradle`. See `// TESTSETUP` below for a
+  similar feature.
   * `// TEST[warning:some warning]`: Expect the response to include a `Warning`
   header. If the response doesn't include a `Warning` header with the exact
   text then the test fails. If the response includes `Warning` headers that
@@ -68,7 +70,9 @@ for its modifiers:
   a test that runs the setup snippet first. See the "painless" docs for a file
   that puts this to good use. This is fairly similar to `// TEST[setup:name]`
   but rather than the setup defined in `docs/build.gradle` the setup is defined
-  right in the documentation file.
+  right in the documentation file. In general, we should prefer `// TESTSETUP`
+  over `// TEST[setup:name]` because it makes it more clear what steps have to
+  be taken before the examples will work.
 
 In addition to the standard CONSOLE syntax these snippets can contain blocks
 of yaml surrounded by markers like this:
diff --git a/docs/build.gradle b/docs/build.gradle
index 790820c9765..5f0caf4f19f 100644
--- a/docs/build.gradle
+++ b/docs/build.gradle
@@ -227,31 +227,6 @@ buildRestTests.doFirst {
     buildRestTests.setups['bank'].replace('#bank_data#', accounts)
 }
 
-buildRestTests.setups['range_index'] = '''
-  - do :
-        indices.create:
-          index: range_index
-          body:
-            settings:
-              number_of_shards: 2
-              number_of_replicas: 1
-            mappings:
-              _doc:
-                properties:
-                  expected_attendees:
-                    type: integer_range
-                  time_frame:
-                    type: date_range
-                    format: yyyy-MM-dd HH:mm:ss||yyyy-MM-dd||epoch_millis
-  - do:
-        bulk:
-          index: range_index
-          type: _doc
-          refresh: true
-          body: |
-            {"index":{"_id": 1}}
-            {"expected_attendees": {"gte": 10, "lte": 20}, "time_frame": {"gte": "2015-10-31 12:00:00", "lte": "2015-11-01"}}'''
-
 // Used by index boost doc
 buildRestTests.setups['index_boost'] = '''
   - do:
diff --git a/docs/reference/mapping/types/range.asciidoc b/docs/reference/mapping/types/range.asciidoc
index a7ab6346176..082d012a490 100644
--- a/docs/reference/mapping/types/range.asciidoc
+++ b/docs/reference/mapping/types/range.asciidoc
@@ -18,6 +18,9 @@ Below is an example of configuring a mapping with various range fields followed
 --------------------------------------------------
 PUT range_index
 {
+  "settings": {
+    "number_of_shards": 2
+  },
   "mappings": {
     "_doc": {
       "properties": {
@@ -33,7 +36,7 @@ PUT range_index
   }
 }
 
-PUT range_index/_doc/1
+PUT range_index/_doc/1?refresh
 {
   "expected_attendees" : { <2>
     "gte" : 10,
@@ -46,6 +49,7 @@ PUT range_index/_doc/1
 }
 --------------------------------------------------
 //CONSOLE
+// TESTSETUP
 
 <1> `date_range` types accept the same field parameters defined by the <<date, `date`>> type.
 <2> Example indexing a meeting with 10 to 20 attendees.
@@ -68,7 +72,6 @@ GET range_index/_search
 }
 --------------------------------------------------
 // CONSOLE
-// TEST[setup:range_index]
 
 The result produced by the above query.
 
@@ -125,7 +128,6 @@ GET range_index/_search
 }
 --------------------------------------------------
 // CONSOLE
-// TEST[setup:range_index]
 
 <1> Range queries work the same as described in <<query-dsl-range-query, range query>>.
 <2> Range queries over range <<mapping-types, fields>> support a `relation` parameter which can be one of `WITHIN`, `CONTAINS`,
@@ -191,7 +193,6 @@ PUT range_index/_doc/2
 }
 --------------------------------------------------
 // CONSOLE
-// TEST[setup:range_index]
 
 [[range-params]]
 ==== Parameters for range fields