diff --git a/docs/painless/index.asciidoc b/docs/painless/index.asciidoc
index 92e0a33bf1347..c41899bbd98da 100644
--- a/docs/painless/index.asciidoc
+++ b/docs/painless/index.asciidoc
@@ -3,7 +3,7 @@
 
 include::../Versions.asciidoc[]
 
-include::painless-getting-started.asciidoc[]
+include::painless-guide.asciidoc[]
 
 include::painless-lang-spec.asciidoc[]
 
diff --git a/docs/painless/painless-contexts.asciidoc b/docs/painless/painless-contexts.asciidoc
index 7c342a3da7a5a..ccc9e3ac4db24 100644
--- a/docs/painless/painless-contexts.asciidoc
+++ b/docs/painless/painless-contexts.asciidoc
@@ -54,6 +54,4 @@ specialized code may define new ways to use a Painless script.
                                     | {xpack-ref}/transform-script.html[Elasticsearch Documentation]
 |====
 
-include::painless-contexts/painless-context-examples.asciidoc[]
-
 include::painless-contexts/index.asciidoc[]
diff --git a/docs/painless/painless-contexts/index.asciidoc b/docs/painless/painless-contexts/index.asciidoc
index 0c8c21c06a9be..11b4c9993374e 100644
--- a/docs/painless/painless-contexts/index.asciidoc
+++ b/docs/painless/painless-contexts/index.asciidoc
@@ -1,3 +1,5 @@
+include::painless-context-examples.asciidoc[]
+
 include::painless-ingest-processor-context.asciidoc[]
 
 include::painless-update-context.asciidoc[]
diff --git a/docs/painless/painless-description.asciidoc b/docs/painless/painless-guide.asciidoc
similarity index 56%
rename from docs/painless/painless-description.asciidoc
rename to docs/painless/painless-guide.asciidoc
index dfaf66ca26d4b..5e926498088ab 100644
--- a/docs/painless/painless-description.asciidoc
+++ b/docs/painless/painless-guide.asciidoc
@@ -1,11 +1,14 @@
+[[painless-guide]]
+== Painless Guide
+
 _Painless_ is a simple, secure scripting language designed specifically for use
 with Elasticsearch. It is the default scripting language for Elasticsearch and
-can safely be used for inline and stored scripts. For a detailed description of
-the Painless syntax and language features, see the
-{painless}/painless-lang-spec.html[Painless Language Specification].
+can safely be used for inline and stored scripts. For a jump start into
+Painless, see <<painless-walkthrough, A Brief Painless Walkthrough>>. For a
+detailed description of the Painless syntax and language features, see the
+<<painless-lang-spec, Painless Language Specification>>.
 
-[[painless-features]]
-You can use Painless anywhere scripts can be used in Elasticsearch. Painless
+You can use Painless anywhere scripts are used in Elasticsearch. Painless
 provides:
 
 * Fast performance: Painless scripts https://benchmarks.elastic.co/index.html#search_qps_scripts[
@@ -18,7 +21,9 @@ complete list of available classes and methods.
 * Optional typing: Variables and parameters can use explicit types or the
 dynamic `def` type.
 
-* Syntax: Extends Java's syntax to provide http://groovy-lang.org/index.html[
-Groovy-style] scripting language features that make scripts easier to write.
+* Syntax: Extends a subset of Java's syntax to provide additional scripting
+language features.
 
 * Optimizations: Designed specifically for Elasticsearch scripting.
+
+include::painless-guide/index.asciidoc[]
\ No newline at end of file
diff --git a/docs/painless/painless-guide/index.asciidoc b/docs/painless/painless-guide/index.asciidoc
new file mode 100644
index 0000000000000..b45406a4e7273
--- /dev/null
+++ b/docs/painless/painless-guide/index.asciidoc
@@ -0,0 +1,7 @@
+include::painless-walkthrough.asciidoc[]
+
+include::painless-method-dispatch.asciidoc[]
+
+include::painless-debugging.asciidoc[]
+
+include::painless-execute-script.asciidoc[]
diff --git a/docs/painless/painless-debugging.asciidoc b/docs/painless/painless-guide/painless-debugging.asciidoc
similarity index 100%
rename from docs/painless/painless-debugging.asciidoc
rename to docs/painless/painless-guide/painless-debugging.asciidoc
diff --git a/docs/painless/painless-execute-script.asciidoc b/docs/painless/painless-guide/painless-execute-script.asciidoc
similarity index 100%
rename from docs/painless/painless-execute-script.asciidoc
rename to docs/painless/painless-guide/painless-execute-script.asciidoc
diff --git a/docs/painless/painless-guide/painless-method-dispatch.asciidoc b/docs/painless/painless-guide/painless-method-dispatch.asciidoc
new file mode 100644
index 0000000000000..0f7d0423174b5
--- /dev/null
+++ b/docs/painless/painless-guide/painless-method-dispatch.asciidoc
@@ -0,0 +1,30 @@
+[[modules-scripting-painless-dispatch]]
+=== How painless dispatches functions
+
+Painless uses receiver, name, and https://en.wikipedia.org/wiki/Arity[arity]
+for method dispatch. For example, `s.foo(a, b)` is resolved by first getting
+the class of `s` and then looking up the method `foo` with two parameters. This
+is different from Groovy which uses the
+https://en.wikipedia.org/wiki/Multiple_dispatch[runtime types] of the
+parameters and Java which uses the compile time types of the parameters.
+
+The consequence of this that Painless doesn't support overloaded methods like
+Java, leading to some trouble when it whitelists classes from the Java
+standard library. For example, in Java and Groovy, `Matcher` has two methods:
+`group(int)` and `group(String)`. Painless can't whitelist both of these methods
+because they have the same name and the same number of parameters. So instead it
+has `group(int)` and `namedGroup(String)`.
+
+We have a few justifications for this different way of dispatching methods:
+
+1. It makes operating on `def` types simpler and, presumably, faster. Using
+receiver, name, and arity means that when Painless sees a call on a `def` object it
+can dispatch the appropriate method without having to do expensive comparisons
+of the types of the parameters. The same is true for invocations with `def`
+typed parameters.
+2. It keeps things consistent. It would be genuinely weird for Painless to
+behave like Groovy if any `def` typed parameters were involved and Java
+otherwise. It'd be slow for it to behave like Groovy all the time.
+3. It keeps Painless maintainable. Adding the Java or Groovy like method
+dispatch *feels* like it'd add a ton of complexity which'd make maintenance and
+other improvements much more difficult.
diff --git a/docs/painless/painless-getting-started.asciidoc b/docs/painless/painless-guide/painless-walkthrough.asciidoc
similarity index 83%
rename from docs/painless/painless-getting-started.asciidoc
rename to docs/painless/painless-guide/painless-walkthrough.asciidoc
index f562033471e31..70089a08726d2 100644
--- a/docs/painless/painless-getting-started.asciidoc
+++ b/docs/painless/painless-guide/painless-walkthrough.asciidoc
@@ -1,10 +1,5 @@
-[[painless-getting-started]]
-== Getting Started with Painless
-
-include::painless-description.asciidoc[]
-
-[[painless-examples]]
-=== Painless Examples
+[[painless-walkthrough]]
+=== A Brief Painless Walkthrough
 
 To illustrate how Painless works, let's load some hockey stats into an Elasticsearch index:
 
@@ -121,7 +116,7 @@ GET hockey/_search
 
 
 [float]
-===== Missing values
+==== Missing values
 
 `doc['field'].value` throws an exception if
 the field is missing in a document.
@@ -198,7 +193,7 @@ POST hockey/_update/1
 ==== Dates
 
 Date fields are exposed as
-`ReadableDateTime`, so they support methods like `getYear`, `getDayOfWeek` 
+`ZonedDateTime`, so they support methods like `getYear`, `getDayOfWeek`
 or e.g. getting milliseconds since epoch with `getMillis`. To use these
 in a script, leave out the `get` prefix and continue with lowercasing the
 rest of the method name. For example, the following returns every hockey 
@@ -365,38 +360,3 @@ Note: all of the `_update_by_query` examples above could really do with a
 {ref}/query-dsl-script-query.html[script query] it wouldn't be as efficient
 as using any other query because script queries aren't able to use the inverted
 index to limit the documents that they have to check.
-
-[[modules-scripting-painless-dispatch]]
-=== How painless dispatches functions
-
-Painless uses receiver, name, and https://en.wikipedia.org/wiki/Arity[arity]
-for method dispatch. For example, `s.foo(a, b)` is resolved by first getting
-the class of `s` and then looking up the method `foo` with two parameters. This
-is different from Groovy which uses the
-https://en.wikipedia.org/wiki/Multiple_dispatch[runtime types] of the
-parameters and Java which uses the compile time types of the parameters.
-
-The consequence of this that Painless doesn't support overloaded methods like
-Java, leading to some trouble when it whitelists classes from the Java
-standard library. For example, in Java and Groovy, `Matcher` has two methods:
-`group(int)` and `group(String)`. Painless can't whitelist both of these methods
-because they have the same name and the same number of parameters. So instead it
-has `group(int)` and `namedGroup(String)`.
-
-We have a few justifications for this different way of dispatching methods:
-
-1. It makes operating on `def` types simpler and, presumably, faster. Using
-receiver, name, and arity means that when Painless sees a call on a `def` object it
-can dispatch the appropriate method without having to do expensive comparisons
-of the types of the parameters. The same is true for invocations with `def`
-typed parameters.
-2. It keeps things consistent. It would be genuinely weird for Painless to
-behave like Groovy if any `def` typed parameters were involved and Java
-otherwise. It'd be slow for it to behave like Groovy all the time.
-3. It keeps Painless maintainable. Adding the Java or Groovy like method
-dispatch *feels* like it'd add a ton of complexity which'd make maintenance and
-other improvements much more difficult.
-
-include::painless-debugging.asciidoc[]
-
-include::painless-execute-script.asciidoc[]
diff --git a/docs/painless/painless-lang-spec.asciidoc b/docs/painless/painless-lang-spec.asciidoc
index d50f3db2dc0d3..2f108c73732eb 100644
--- a/docs/painless/painless-lang-spec.asciidoc
+++ b/docs/painless/painless-lang-spec.asciidoc
@@ -17,38 +17,4 @@ into Java Virtual Machine (JVM) byte code and executed against a standard JVM.
 This specification uses ANTLR4 grammar notation to describe the allowed syntax.
 However, the actual Painless grammar is more compact than what is shown here.
 
-include::painless-comments.asciidoc[]
-
-include::painless-keywords.asciidoc[]
-
-include::painless-literals.asciidoc[]
-
-include::painless-identifiers.asciidoc[]
-
-include::painless-variables.asciidoc[]
-
-include::painless-types.asciidoc[]
-
-include::painless-casting.asciidoc[]
-
-include::painless-operators.asciidoc[]
-
-include::painless-operators-general.asciidoc[]
-
-include::painless-operators-numeric.asciidoc[]
-
-include::painless-operators-boolean.asciidoc[]
-
-include::painless-operators-reference.asciidoc[]
-
-include::painless-operators-array.asciidoc[]
-
-include::painless-statements.asciidoc[]
-
-include::painless-scripts.asciidoc[]
-
-include::painless-functions.asciidoc[]
-
-include::painless-lambdas.asciidoc[]
-
-include::painless-regexes.asciidoc[]
+include::painless-lang-spec/index.asciidoc[]
\ No newline at end of file
diff --git a/docs/painless/painless-lang-spec/index.asciidoc b/docs/painless/painless-lang-spec/index.asciidoc
new file mode 100644
index 0000000000000..e75264ff3e4e1
--- /dev/null
+++ b/docs/painless/painless-lang-spec/index.asciidoc
@@ -0,0 +1,35 @@
+include::painless-comments.asciidoc[]
+
+include::painless-keywords.asciidoc[]
+
+include::painless-literals.asciidoc[]
+
+include::painless-identifiers.asciidoc[]
+
+include::painless-variables.asciidoc[]
+
+include::painless-types.asciidoc[]
+
+include::painless-casting.asciidoc[]
+
+include::painless-operators.asciidoc[]
+
+include::painless-operators-general.asciidoc[]
+
+include::painless-operators-numeric.asciidoc[]
+
+include::painless-operators-boolean.asciidoc[]
+
+include::painless-operators-reference.asciidoc[]
+
+include::painless-operators-array.asciidoc[]
+
+include::painless-statements.asciidoc[]
+
+include::painless-scripts.asciidoc[]
+
+include::painless-functions.asciidoc[]
+
+include::painless-lambdas.asciidoc[]
+
+include::painless-regexes.asciidoc[]
diff --git a/docs/painless/painless-casting.asciidoc b/docs/painless/painless-lang-spec/painless-casting.asciidoc
similarity index 100%
rename from docs/painless/painless-casting.asciidoc
rename to docs/painless/painless-lang-spec/painless-casting.asciidoc
diff --git a/docs/painless/painless-comments.asciidoc b/docs/painless/painless-lang-spec/painless-comments.asciidoc
similarity index 100%
rename from docs/painless/painless-comments.asciidoc
rename to docs/painless/painless-lang-spec/painless-comments.asciidoc
diff --git a/docs/painless/painless-functions.asciidoc b/docs/painless/painless-lang-spec/painless-functions.asciidoc
similarity index 100%
rename from docs/painless/painless-functions.asciidoc
rename to docs/painless/painless-lang-spec/painless-functions.asciidoc
diff --git a/docs/painless/painless-identifiers.asciidoc b/docs/painless/painless-lang-spec/painless-identifiers.asciidoc
similarity index 100%
rename from docs/painless/painless-identifiers.asciidoc
rename to docs/painless/painless-lang-spec/painless-identifiers.asciidoc
diff --git a/docs/painless/painless-keywords.asciidoc b/docs/painless/painless-lang-spec/painless-keywords.asciidoc
similarity index 100%
rename from docs/painless/painless-keywords.asciidoc
rename to docs/painless/painless-lang-spec/painless-keywords.asciidoc
diff --git a/docs/painless/painless-lambdas.asciidoc b/docs/painless/painless-lang-spec/painless-lambdas.asciidoc
similarity index 100%
rename from docs/painless/painless-lambdas.asciidoc
rename to docs/painless/painless-lang-spec/painless-lambdas.asciidoc
diff --git a/docs/painless/painless-literals.asciidoc b/docs/painless/painless-lang-spec/painless-literals.asciidoc
similarity index 100%
rename from docs/painless/painless-literals.asciidoc
rename to docs/painless/painless-lang-spec/painless-literals.asciidoc
diff --git a/docs/painless/painless-operators-array.asciidoc b/docs/painless/painless-lang-spec/painless-operators-array.asciidoc
similarity index 100%
rename from docs/painless/painless-operators-array.asciidoc
rename to docs/painless/painless-lang-spec/painless-operators-array.asciidoc
diff --git a/docs/painless/painless-operators-boolean.asciidoc b/docs/painless/painless-lang-spec/painless-operators-boolean.asciidoc
similarity index 100%
rename from docs/painless/painless-operators-boolean.asciidoc
rename to docs/painless/painless-lang-spec/painless-operators-boolean.asciidoc
diff --git a/docs/painless/painless-operators-general.asciidoc b/docs/painless/painless-lang-spec/painless-operators-general.asciidoc
similarity index 100%
rename from docs/painless/painless-operators-general.asciidoc
rename to docs/painless/painless-lang-spec/painless-operators-general.asciidoc
diff --git a/docs/painless/painless-operators-numeric.asciidoc b/docs/painless/painless-lang-spec/painless-operators-numeric.asciidoc
similarity index 100%
rename from docs/painless/painless-operators-numeric.asciidoc
rename to docs/painless/painless-lang-spec/painless-operators-numeric.asciidoc
diff --git a/docs/painless/painless-operators-reference.asciidoc b/docs/painless/painless-lang-spec/painless-operators-reference.asciidoc
similarity index 100%
rename from docs/painless/painless-operators-reference.asciidoc
rename to docs/painless/painless-lang-spec/painless-operators-reference.asciidoc
diff --git a/docs/painless/painless-operators.asciidoc b/docs/painless/painless-lang-spec/painless-operators.asciidoc
similarity index 100%
rename from docs/painless/painless-operators.asciidoc
rename to docs/painless/painless-lang-spec/painless-operators.asciidoc
diff --git a/docs/painless/painless-regexes.asciidoc b/docs/painless/painless-lang-spec/painless-regexes.asciidoc
similarity index 100%
rename from docs/painless/painless-regexes.asciidoc
rename to docs/painless/painless-lang-spec/painless-regexes.asciidoc
diff --git a/docs/painless/painless-scripts.asciidoc b/docs/painless/painless-lang-spec/painless-scripts.asciidoc
similarity index 100%
rename from docs/painless/painless-scripts.asciidoc
rename to docs/painless/painless-lang-spec/painless-scripts.asciidoc
diff --git a/docs/painless/painless-statements.asciidoc b/docs/painless/painless-lang-spec/painless-statements.asciidoc
similarity index 100%
rename from docs/painless/painless-statements.asciidoc
rename to docs/painless/painless-lang-spec/painless-statements.asciidoc
diff --git a/docs/painless/painless-types.asciidoc b/docs/painless/painless-lang-spec/painless-types.asciidoc
similarity index 100%
rename from docs/painless/painless-types.asciidoc
rename to docs/painless/painless-lang-spec/painless-types.asciidoc
diff --git a/docs/painless/painless-variables.asciidoc b/docs/painless/painless-lang-spec/painless-variables.asciidoc
similarity index 100%
rename from docs/painless/painless-variables.asciidoc
rename to docs/painless/painless-lang-spec/painless-variables.asciidoc
diff --git a/docs/painless/painless-xref.asciidoc b/docs/painless/painless-xref.asciidoc
deleted file mode 100644
index 86407b3e697d6..0000000000000
--- a/docs/painless/painless-xref.asciidoc
+++ /dev/null
@@ -1,2 +0,0 @@
-Ready to start scripting with Painless? See {painless}/painless-getting-started.html[Getting Started with Painless] in the guide to the
-{painless}/painless.html[Painless Scripting Language].
\ No newline at end of file
diff --git a/docs/reference/ingest/ingest-node.asciidoc b/docs/reference/ingest/ingest-node.asciidoc
index 1f8abc5675db9..b1a92222bec59 100644
--- a/docs/reference/ingest/ingest-node.asciidoc
+++ b/docs/reference/ingest/ingest-node.asciidoc
@@ -563,7 +563,7 @@ template for all indexes that hold data that needs pre-index processing.
 [[conditionals-with-regex]]
 === Conditionals with the Regular Expressions
 The `if` conditional is implemented as a Painless script, which requires
-{painless}//painless-examples.html#modules-scripting-painless-regex[explicit support for regular expressions].
+{painless}//painless-regexes.html[explicit support for regular expressions].
 
 `script.painless.regex.enabled: true` must be set in `elasticsearch.yml` to use regular
 expressions in the `if` condition.
diff --git a/docs/reference/modules/scripting/painless.asciidoc b/docs/reference/modules/scripting/painless.asciidoc
index ac48aad73d28f..6dd9b50db51ed 100644
--- a/docs/reference/modules/scripting/painless.asciidoc
+++ b/docs/reference/modules/scripting/painless.asciidoc
@@ -1,7 +1,32 @@
 [[modules-scripting-painless]]
 === Painless Scripting Language
 
-include::../../../painless/painless-description.asciidoc[]
+_Painless_ is a simple, secure scripting language designed specifically for use
+with Elasticsearch. It is the default scripting language for Elasticsearch and
+can safely be used for inline and stored scripts. To get started with
+Painless, see the {painless}/painless-guide.html[Painless Guide]. For a
+detailed description of the Painless syntax and language features, see the
+{painless}/painless-lang-spec.html[Painless Language Specification].
 
-Ready to start scripting with Painless? See {painless}/painless-getting-started.html[Getting Started with Painless] in the guide to the
+[[painless-features]]
+You can use Painless anywhere scripts can be used in Elasticsearch. Painless
+provides:
+
+* Fast performance: Painless scripts https://benchmarks.elastic.co/index.html#search_qps_scripts[
+run several times faster] than the alternatives.
+
+* Safety: Fine-grained whitelist with method call/field granularity. See the
+{painless}/painless-api-reference.html[Painless API Reference] for a
+complete list of available classes and methods.
+
+* Optional typing: Variables and parameters can use explicit types or the
+dynamic `def` type.
+
+* Syntax: Extends a subset of Java's syntax to provide additional scripting
+language features.
+
+* Optimizations: Designed specifically for Elasticsearch scripting.
+
+Ready to start scripting with Painless? See the
+{painless}/painless-guide.html[Painless Guide] for the
 {painless}/index.html[Painless Scripting Language].
\ No newline at end of file