document the thing (#765)

Author: fhennig

docs/modules/zookeeper/pages/index.adoc

@@ -6,8 +6,8 @@ The Stackable Operator for Apache ZooKeeper is a Kubernetes Operator for deployi
 https://zookeeper.apache.org/[Apache ZooKeeper] ensembles. Apache ZooKeeper is an open-source distributed coordination
 service that facilitates synchronization, configuration management and leader election in distributed systems. ZooKeeper
 is often used for these tasks in the Apache Hadoop ecosystem. Within the Stackable Platform, the Stackable Operators for
-xref:hbase:index.adoc[Apache HBase], xref:hdfs:index.adoc[Apache Hadoop HDFS], xref:kafka:index.adoc[Apache Kafka] and
-xref:nifi:index.adoc[Apache NiFi] depend on the ZooKeeper Operator.
+xref:hbase:index.adoc[Apache HBase], xref:hdfs:index.adoc[Apache Hadoop HDFS], xref:kafka:index.adoc[Apache Kafka], 
+xref:nifi:index.adoc[Apache NiFi] and xref:druid:index.adoc[Apache Druid] depend on the ZooKeeper Operator.
 
 == Getting started
 
@@ -29,7 +29,7 @@ role group is accessible through its own Service, and there is a Service for the
 
 The Operator creates a xref:concepts:service_discovery.adoc[service discovery ConfigMap] for the ZooKeeper instance, as
 well as for each ZNode. The discovery ConfigMaps contain information on how to connect to ZooKeeper. The ZNode discovery
-ConfigMap give access information for the ZNode. xref:zookeeper:znodes.adoc[learn more about ZNodes].
+ConfigMap give access information for the ZNode. xref:zookeeper:znodes.adoc[Learn more about ZNodes].
 
 == Dependencies
 

docs/modules/zookeeper/pages/znodes.adoc

@@ -8,6 +8,19 @@ as it sees fit. This can be thought of like a namespace for that client, and pre
 
 The Stackable Operator for Apache ZooKeeper manages ZNodes using the _ZookeeperZnode_ resource. 
 
+IMPORTANT: The Operator connects directly to ZooKeeper to manage the ZNodes inside of the ZooKeeper ensemble. This means that network access to the ZooKeeper pods is necessary. If your Kubernetes cluster restricts network acess, you need to configure a NetworkPolicy to allow the operator to connect to ZooKeeper.
+
+== Configuring ZNodes
+
+ZNodes are configured with the ZookeeperZnode CustomResource.
+If a ZookeeperZnode resource is created, the operator will create the respective tree in ZooKeeper.
+Also, if the resource in Kubernetes is deleted, so is the data in ZooKeeper.
+
+CAUTION: The operator automatically deletes the ZNode from the ZooKeeper cluster if the Kubernetes `ZookeeperZnode` object is deleted. Recreating the
+`ZookeeperZnode` object will not restore access to the data.
+
+Here is an example of a ZookeeperZnode:
+
 [source,yaml]
 ----
 include::example$example-znode.yaml[]
@@ -16,14 +29,17 @@ include::example$example-znode.yaml[]
 <2> Reference to the `ZookeeperCluster` object where the ZNode should be created.
 <3> The namespace of the `ZookeeperCluster`. Can be omitted and will default to the namespace of the ZNode object.
 
-NOTE: It is the responsibility of the user to ensure that ZNodes are not shared between products. For example, a Kafka and a Hadoop cluster should not share the same ZNode.
-
 When a ZNode is created, the operator creates the required tree in ZooKeeper and a xref:concepts:service_discovery.adoc[discovery ConfigMap] with a xref:discovery.adoc[] for this ZNode. This discovery ConfigMap is used by other operators to configure clients with access to the ZNode. 
 
 The operator _does not_ manage the contents of the ZNode.
 
-CAUTION: The operator automatically deletes the ZNode from the ZooKeeper cluster if the Kubernetes `ZookeeperZnode` object is deleted. Recreating the
-`ZookeeperZnode` object will not restore access to the data.
+
+== Creating a ZNode per dependant
+
+To ensure that a product that uses ZooKeeper is running smoothly, you should make sure that each Stacklet or product instance is operating with its own ZNode.
+For example, a Kafka and a Hadoop cluster should not share the same ZNode. Also no two Kafka instances should share the same ZNode.
+
+Have a look at the xref:usage_guide/isolating_clients_with_znodes.adoc[] guide for hands-on instructions on how to set up multiple ZNodes for different Stacklets.
 
 == Split responsibilities for ZooKeeper and ZNodes
 
@@ -35,4 +51,4 @@ ZNodes however are product specific and need to be managed by product teams that
 
 == What's next
 
-Have a look at the usage guide for ZNodes: xref:usage_guide/isolating_clients_with_znodes.adoc[]
+Have a look at the usage guide for ZNodes: xref:usage_guide/isolating_clients_with_znodes.adoc[] or the CRD reference for the {crd-docs}/zookeeper.stackable.tech/zookeeperznode/v1alpha1/[ZookeeperZnode {external-link-icon}^] CustomResource.