diff --git a/akka-docs/src/main/paradox/additional/deploy.md b/akka-docs/src/main/paradox/additional/deploy.md
index 14cbd846b2..76a7945658 100644
--- a/akka-docs/src/main/paradox/additional/deploy.md
+++ b/akka-docs/src/main/paradox/additional/deploy.md
@@ -1,12 +1,21 @@
# How can I deploy Akka?
-Akka can be used in different ways:
+The simplest way to use Akka is as a regular library, adding the Akka jars you
+need to your classpath (in case of a web app, in `WEB-INF/lib`).
- * As a library: used as a regular JAR on the classpath and/or in a web app, to
-be put into `WEB-INF/lib`
- * As an application packaged with [sbt-native-packager](https://github.com/sbt/sbt-native-packager)
+Sometimes it can be useful to bundle your application into a single 'fat jar'.
+If you do that, some additional configuration is needed, because each Akka jar
+contains a `reference.conf` resource with default values, and these must be
+merged.
+
+How to make sure reference.conf resources are merged depends on the tooling you
+are using to create the fat jar:
+
+ * When using sbt: as an application packaged with [sbt-native-packager](https://github.com/sbt/sbt-native-packager)
+ * When using Maven: as an application packaged with a bundler such as jarjar, onejar or assembly
+ * When using Gradle: using the Jar task from the Java plugin
-## Native Packager
+## sbt: Native Packager
[sbt-native-packager](https://github.com/sbt/sbt-native-packager) is a tool for creating
distributions of any type of application, including Akka applications.
@@ -25,6 +34,78 @@ addSbtPlugin("com.typesafe.sbt" % "sbt-native-packager" % "1.1.5")
Follow the instructions for the `JavaAppPackaging` in the [sbt-native-packager plugin documentation](http://sbt-native-packager.readthedocs.io/en/latest/archetypes/java_app/index.html).
+## Maven: jarjar, onejar or assembly
+
+You can use the [Apache Maven Shade Plugin](http://maven.apache.org/plugins/maven-shade-plugin)
+support for [Resource Transformers](http://maven.apache.org/plugins/maven-shade-plugin/examples/resource-transformers.html#AppendingTransformer)
+to merge all the reference.confs on the build classpath into one.
+
+The plugin configuration might look like this:
+
+```
+
+ org.apache.maven.plugins
+ maven-shade-plugin
+ 1.5
+
+
+ package
+
+ shade
+
+
+ true
+ allinone
+
+
+ *:*
+
+
+
+
+ reference.conf
+
+
+
+ akka.Main
+
+
+
+
+
+
+
+```
+
+
+## Gradle: the Jar task from the Java plugin
+
+When using Gradle, you would typically use the
+[Jar task from the Java plugin](https://www.baeldung.com/gradle-fat-jar)
+to create the fat jar.
+
+To make sure the `reference.conf` resources are correctly merged, you might
+use the [Shadow plugin](https://imperceptiblethoughts.com/shadow/), which might
+look something like this:
+
+```
+import com.github.jengelman.gradle.plugins.shadow.transformers.AppendingTransformer
+
+plugins {
+ id 'java'
+ id "com.github.johnrengelman.shadow" version "5.0.0"
+}
+
+shadowJar {
+ transform(AppendingTransformer) {
+ resource = 'reference.conf'
+ }
+ with jar
+}
+```
+
## In a Docker container
You can use both Akka remoting and Akka Cluster inside of Docker containers. But note
diff --git a/akka-docs/src/main/paradox/general/configuration.md b/akka-docs/src/main/paradox/general/configuration.md
index 550675a5f0..252fa995ae 100644
--- a/akka-docs/src/main/paradox/general/configuration.md
+++ b/akka-docs/src/main/paradox/general/configuration.md
@@ -67,56 +67,15 @@ of the JAR file.
@@@ warning
Akka's configuration approach relies heavily on the notion of every
-module/jar having its own reference.conf file, all of these will be
+module/jar having its own `reference.conf` file. All of these will be
discovered by the configuration and loaded. Unfortunately this also means
that if you put/merge multiple jars into the same jar, you need to merge all the
-reference.confs as well. Otherwise all defaults will be lost and Akka will not function.
+`reference.conf` files as well: otherwise all defaults will be lost.
@@@
-If you are using Maven to package your application, you can also make use of
-the [Apache Maven Shade Plugin](http://maven.apache.org/plugins/maven-shade-plugin) support for [Resource
-Transformers](http://maven.apache.org/plugins/maven-shade-plugin/examples/resource-transformers.html#AppendingTransformer)
-to merge all the reference.confs on the build classpath into one.
-
-The plugin configuration might look like this:
-
-```
-
- org.apache.maven.plugins
- maven-shade-plugin
- 1.5
-
-
- package
-
- shade
-
-
- true
- allinone
-
-
- *:*
-
-
-
-
- reference.conf
-
-
-
- akka.Main
-
-
-
-
-
-
-
-```
+See the @ref[deployment documentation](../additional/deploy.md)
+for information on how to merge the `reference.conf` resources while bundling.
## Custom application.conf