diff --git a/docs/reference/query-dsl/span-within-query.asciidoc b/docs/reference/query-dsl/span-within-query.asciidoc
index f344f32b21854..38f9bb8dce679 100644
--- a/docs/reference/query-dsl/span-within-query.asciidoc
+++ b/docs/reference/query-dsl/span-within-query.asciidoc
@@ -4,33 +4,48 @@
 <titleabbrev>Span within</titleabbrev>
 ++++
 
-Returns matches which are enclosed inside another span query. The span within
-query maps to Lucene `SpanWithinQuery`. Here is an example:
+Returns spans from a `little` <<span-queries,span query>> that are enclosed in
+spans matching a `big` span query.
+
+
+[[span-within-query-ex-request]]
+==== Example request
 
 [source,js]
---------------------------------------------------
+----
 GET /_search
 {
     "query": {
         "span_within" : {
-            "little" : {
-                "span_term" : { "field1" : "foo" }
-            },
             "big" : {
                 "span_near" : { 
                     "clauses" : [
-                        { "span_term" : { "field1" : "bar" } },
-                        { "span_term" : { "field1" : "baz" } }
+                        { "span_term" : { "message" : { "value" : "bar" } } },
+                        { "span_term" : { "message" : { "value" : "baz" } } }
                     ],
                     "slop" : 5,
                     "in_order" : true
                 }
+            },
+            "little" : {
+                "span_term" : { "message" : { "value" : "foo" } } 
             }
         }
     }
 }
---------------------------------------------------
+----
 // CONSOLE
 
-The `big` and `little` clauses can be any span type query. Matching
-spans from `little` that are enclosed within `big` are returned.
+
+[[span-within-top-level-params]]
+==== Top-level parameters for `span_within`
+
+`big`::
+(Required, query object) Contains a <<span-queries,span query>>. To be returned,
+spans matching the `little` span query must be enclosed in spans matching this
+query.
+
+`little`::
+(Required, query object) Contains a <<span-queries,span query>>. To be returned,
+spans matching this span query must be enclosed in spans matching the `big`
+query.