diff --git a/README.adoc b/README.adoc
index 08128845..b3dd55c4 100644
--- a/README.adoc
+++ b/README.adoc
@@ -184,6 +184,16 @@ spring.cloud.kubernetes.discovery.all-namespaces=true
 ----
 ====
 
+To discover services and endpoints only from specified namespaces you should set property `all-namespaces` to `false` and set the following property in `application.properties` (in this example namespaces are: `ns1` and `ns2`).
+
+====
+[source]
+----
+spring.cloud.kubernetes.discovery.namespaces[0]=ns1
+spring.cloud.kubernetes.discovery.namespaces[1]=ns2
+----
+====
+
 To discover service endpoint addresses that are not marked as "ready" by the kubernetes api server, you can set the following property in `application.properties` (default: false):
 
 ====
@@ -223,7 +233,17 @@ this to work, you need to align the Kubernetes service name with the `spring.app
 NOTE:  `spring.application.name` has no effect as far as the name registered for the application within Kubernetes
 
 Spring Cloud Kubernetes can also watch the Kubernetes service catalog for changes and update the
-`DiscoveryClient` implementation accordingly.  In order to enable this functionality you need to add
+`DiscoveryClient` implementation accordingly. By "watch" we mean that we will publish a heartbeat event every `spring.cloud.kubernetes.discovery.catalog-services-watch-delay`
+milliseconds (by default it is `30000`). The heartbeat event will contain the target references (and their namespaces of the addresses of all endpoints
+(for the exact details of what will get returned you can take a look inside `KubernetesCatalogWatch`). This is an implementation detail, and listeners of the heartbeat event
+should not rely on the details. Instead, they should see if there are differences between two subsequent heartbeats via `equals` method. We will take care to return a correct implementation that adheres to the equals contract.
+The endpoints will be queried in either all namespaces (enabled via `spring.cloud.kubernetes.discovery.all-namespaces=true`), or
+we will use: xref:property-source-config.adoc#namespace-resolution[Namespace Resolution].
+
+
+
+
+In order to enable this functionality you need to add
 `@EnableScheduling` on a configuration class in your application.
 
 == Kubernetes native service discovery
diff --git a/docs/src/main/asciidoc/_configprops.adoc b/docs/src/main/asciidoc/_configprops.adoc
index 63559ea3..fc94dbf3 100644
--- a/docs/src/main/asciidoc/_configprops.adoc
+++ b/docs/src/main/asciidoc/_configprops.adoc
@@ -59,8 +59,7 @@
 |spring.cloud.kubernetes.config.sources |  | 
 |spring.cloud.kubernetes.config.use-name-as-prefix | `+++false+++` | 
 |spring.cloud.kubernetes.discovery.all-namespaces | `+++false+++` | 
-|spring.cloud.kubernetes.discovery.namespaces | `+++[]+++` |
-|spring.cloud.kubernetes.discovery.cache-loading-timeout-seconds | `+++60+++` |
+|spring.cloud.kubernetes.discovery.cache-loading-timeout-seconds | `+++60+++` | 
 |spring.cloud.kubernetes.discovery.enabled | `+++true+++` | 
 |spring.cloud.kubernetes.discovery.filter |  | 
 |spring.cloud.kubernetes.discovery.include-not-ready-addresses | `+++false+++` | 
@@ -71,6 +70,7 @@
 |spring.cloud.kubernetes.discovery.metadata.annotations-prefix |  | 
 |spring.cloud.kubernetes.discovery.metadata.labels-prefix |  | 
 |spring.cloud.kubernetes.discovery.metadata.ports-prefix | `+++port.+++` | 
+|spring.cloud.kubernetes.discovery.namespaces |  | 
 |spring.cloud.kubernetes.discovery.order | `+++0+++` | 
 |spring.cloud.kubernetes.discovery.primary-port-name |  | 
 |spring.cloud.kubernetes.discovery.service-labels |  |