diff --git a/README.adoc b/README.adoc
index 21c4432e..d9d090f5 100644
--- a/README.adoc
+++ b/README.adoc
@@ -272,6 +272,9 @@ spring:
 
 In the preceding example, if `spring.cloud.kubernetes.config.namespace` had not been set,
 the `ConfigMap` named `c1` would be looked up in the namespace that the application runs.
+See <<namespace-resolution,Namespace resolution>> to get a better understanding of how the namespace
+of the application is resolved.
+
 
 Any matching `ConfigMap` that is found is processed as follows:
 
@@ -788,7 +791,7 @@ spring:
         sources:
          # Spring Cloud Kubernetes looks up a Secret named s1 in namespace default-namespace
          - name: s1
-         # Spring Cloud Kubernetes looks up a Secret named default-name in whatever namespace n2
+         # Spring Cloud Kubernetes looks up a Secret named default-name in namespace n2
          - namespace: n2
          # Spring Cloud Kubernetes looks up a Secret named s3 in namespace n3
          - namespace: n3
@@ -798,6 +801,8 @@ spring:
 
 In the preceding example, if `spring.cloud.kubernetes.secrets.namespace` had not been set,
 the `Secret` named `s1` would be looked up in the namespace that the application runs.
+See <<namespace-resolution,namespace-resolution>> to get a better understanding of how the namespace
+of the application is resolved.
 
 
 .Properties:
@@ -823,6 +828,44 @@ https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-Configuration-Bi
 You can find an example of an application that uses secrets (though it has not been updated to use the new `spring-cloud-kubernetes` project) at
 https://github.com/fabric8-quickstarts/spring-boot-camel-config[spring-boot-camel-config]
 
+[[namespace-resolution]]
+=== Namespace resolution
+Finding an application namespace happens on a best-effort basis. There are some steps that we iterate in order
+to find it. The easiest and most common one, is to specify it in the proper configuration, for example:
+
+====
+[source,yaml]
+----
+spring:
+  application:
+    name: app
+  cloud:
+    kubernetes:
+      secrets:
+        name: secret
+        namespace: default
+        sources:
+         # Spring Cloud Kubernetes looks up a Secret named 'a' in namespace 'default'
+         - name: a
+         # Spring Cloud Kubernetes looks up a Secret named 'secret' in namespace 'b'
+         - namespace: b
+         # Spring Cloud Kubernetes looks up a Secret named 'd' in namespace 'c'
+         - namespace: c
+           name: d
+----
+====
+
+Remember that the same can be done for config maps. If such a namespace is not specified, it will be read (in this order):
+
+1. from property `spring.cloud.kubernetes.client.namespace`
+2. from a String residing in a file denoted by `spring.cloud.kubernetes.client.serviceAccountNamespacePath` property
+3. from a String residing in `/var/run/secrets/kubernetes.io/serviceaccount/namespace` file
+(kubernetes default namespace path)
+4. from a designated client method call (for example fabric8's : `KubernetesClient::getNamespace`), if the client provides
+such a method.
+
+Failure to find a namespace from the above steps will result in an Exception being raised.
+
 === `PropertySource` Reload
 
 WARNING:  This functionality has been deprecated in the 2020.0 release.  Please see