Enhance HV-VES documentation

Change-Id: Iba32c9a19ea3d11c4e541f90ee1afa57176fe7f7
Signed-off-by: Jakub Dudycz <jakub.dudycz@nokia.com>
Issue-ID: DCAEGEN2-1493

6 files changed, 24 insertions, 22 deletions

diff --git a/docs/sections/apis/ves-hv/index.rst b/docs/sections/apis/ves-hv/index.rst
index c61c1e16..df91681c 100644
--- a/docs/sections/apis/ves-hv/index.rst
+++ b/docs/sections/apis/ves-hv/index.rst
@@ -25,7 +25,8 @@ TCP Endpoint
 ============
 
 HV-VES is exposed as NodePort service on Kubernetes cluster on port 30222/tcp.
-It uses plain, insecure TCP connection without socket data encryption. In Casablanca release, there is an experimental option to enable SSL/TLS (see :ref:`ssl_tls_authorization`).
+It uses plain, insecure TCP connection without socket data encryption. In Dublin release,
+there is an experimental option to enable SSL/TLS (see :ref:`ssl_tls_authorization`).
 Without TLS client authentication/authorization is not possible.
 Connections are stream-based (as opposed to request-based) and long-running.
 
@@ -54,9 +55,8 @@ HV-VES Collector forwards incoming messages to a particular DMaaP Kafka topic ba
 
 In both cases raw bytes might be extracted using ``org.apache.kafka.common.serialization.ByteArrayDeserializer``. The resulting bytes might be further passed to ``parseFrom`` methods included in classes generated from GPB definitions. WTP is not used here - it is only used in communication between PNF/VNF and the collector.
 
-By default, **HV-VES** will use routing defined in **k8s-hv-ves.yaml-template** in **dcaegen2/platform/blueprints project**. Currently defined domain->topic mapping looks as follows:
-
-- perf3gpp -> HV_VES_PERF3GPP
+By default, **HV-VES** will use routing defined in **k8s-hv-ves.yaml-template** in **dcaegen2/platform/blueprints project**.
+Currently there is one domain->topic mapping defined: perf3gpp->HV_VES_PERF3GPP
 
 
 .. _supported_domains:
@@ -64,9 +64,7 @@ By default, **HV-VES** will use routing defined in **k8s-hv-ves.yaml-template**
 Supported domains
 =================
 
-Domains supported by **HV-VES**:
-
-- perf3gpp
+As for now **HV-VES** supports only **perf3gpp** domain
 
 For domains descriptions, see :ref:`domains_supported_by_hvves`
 
diff --git a/docs/sections/services/ves-hv/deployment.rst b/docs/sections/services/ves-hv/deployment.rst
index 3a14eb18..caad3978 100644
--- a/docs/sections/services/ves-hv/deployment.rst
+++ b/docs/sections/services/ves-hv/deployment.rst
@@ -22,7 +22,7 @@ Currently HV-VES requires single command line parameter which points to base con
 
     configuration-file ; c ; yes ; VESHV_CONFIGURATION_FILE  ; Path to JSON file containing HV-VES configuration
 
-Environment variables that are required by HV-VES are used by collector for provisioning of run-time configuration and are usually provided by DCAE platform.
+Environment variables that are required by HV-VES are used by collector for provisioning of run-time configuration and are provided by DCAE platform.
 
 .. csv-table::
     :widths: auto
@@ -68,7 +68,7 @@ Tables show restrictions on fields in file configuration and short description.
     Server
     Key                         ; Value type ; Description
     server.listenPort           ; number     ; Port on which HV-VES listens internally
-    server.idleTimeoutSec       ; number     ; Idle timeout for remote hosts. After given time without any data exchange, the connection might be closed
+    server.idleTimeoutSec       ; number     ; Idle timeout for remote hosts. After given time without any data exchange, the connection is closed
 
 .. csv-table::
     :widths: auto
@@ -93,7 +93,7 @@ Tables show restrictions on fields in file configuration and short description.
     security.keys.trustStoreFile          ; String     ; Path to file with trusted certificates bundle used in HV-VES incoming connections
     security.keys.trustStorePasswordFile  ; String     ; Trust store password file used in HV-VES incoming connections
 
-All security entries are mandatory with `security.sslDisable` set to `false`. Otherwise only `security.sslDisable` needs to be specified. If `security.sslDisable` flag is missing, then it is  interpreted same as it would be set to `false`.
+All security entries are mandatory with `security.sslDisable` set to `false`. Otherwise only `security.sslDisable` needs to be specified. If `security.sslDisable` flag is missing, then it is  interpreted as it was set to `false`.
 
 .. csv-table::
     :widths: auto
@@ -127,7 +127,7 @@ You can also see current replicas amount under a corresponding column.
     ONAP_NAMESPACE=onap
     kubectl get --namespace ${ONAP_NAMESPACE} deployment
 
-3. To scale deployment execute:
+3. To scale deployment, execute the following commands:
 
 .. code-block:: bash
 
diff --git a/docs/sections/services/ves-hv/design.rst b/docs/sections/services/ves-hv/design.rst
index fb4fa2c7..6bc7c77d 100644
--- a/docs/sections/services/ves-hv/design.rst
+++ b/docs/sections/services/ves-hv/design.rst
@@ -14,7 +14,7 @@ HV-VES Collector is a high-volume variant of the existing VES (JSON) collector,
 HV-VES follows the VES-JSON schema as much as possible.
 
 - HV-VES uses a Google Protocol Buffers (GPB, proto files) representation of the VES Common Header.
-- The proto files use most encoding effective types defined by GPB to cover Common Header fields.
+- The proto files use most encoding-effective types defined by GPB to cover Common Header fields.
 - HV-VES makes routing decisions based mostly on the content of the **Domain** parameter.
 - HV-VES allows to embed Payload of different types (by default perf3gpp domain is included).
 
diff --git a/docs/sections/services/ves-hv/repositories.rst b/docs/sections/services/ves-hv/repositories.rst
index 98034f20..40f7400a 100644
--- a/docs/sections/services/ves-hv/repositories.rst
+++ b/docs/sections/services/ves-hv/repositories.rst
@@ -12,7 +12,7 @@ Full image name is `onap/org.onap.dcaegen2.collectors.hv-ves.hv-collector-main`_
 
 .. _`onap/org.onap.dcaegen2.collectors.hv-ves.hv-collector-main`: https://nexus3.onap.org/#browse/search=keyword%3Dmain:7f6379d32f8dd78f1ec5ed038decc99e
 
-There are also simulators published as docker images. Those simulators are used internally during CSIT tests.
+There are also simulators published as docker images. Those simulators are used internally during **Continuous System and Integration Testing**
 
 Full simulators' names are `onap/org.onap.dcaegen2.collectors.hv-ves.hv-collector-dcae-app-simulator`_ and `onap/org.onap.dcaegen2.collectors.hv-ves.hv-collector-xnf-simulator`_.
 
diff --git a/docs/sections/services/ves-hv/run-time-configuration.rst b/docs/sections/services/ves-hv/run-time-configuration.rst
index 95bad674..bac68ecf 100644
--- a/docs/sections/services/ves-hv/run-time-configuration.rst
+++ b/docs/sections/services/ves-hv/run-time-configuration.rst
@@ -9,7 +9,7 @@ Run-Time configuration
 HV-VES dynamic configuration is primarily meant to provide DMaaP Connection Objects (see :ref:`dmaap-connection-objects`).
 These objects contain information necessary to route received VES Events to correct Kafka topic. This metadata will be later referred to as Routing definition.
 
-Collector internally uses DCAE-SDK to fetch configuration from Config Binding Service.
+Collector uses DCAE-SDK internally, to fetch configuration from Config Binding Service.
 
 HV-VES waits 10 seconds (default, configurable during deployment with **firstRequestDelay** option, see :ref:`configuration_file`) before the first attempt to retrieve configuration from CBS. This is to prevent possible synchronization issues. During that time HV-VES declines any connection attempts from xNF (VNF/PNF).
 
@@ -22,21 +22,22 @@ Configuration format
 --------------------
 
 Following JSON format presents dynamic configuration options recognized by HV-VES Collector.
-Note that there is no verification of the data correctness (e.g. if specified security files are present on machine) and thus invalid data can result in service malfunctioning or even container shutdown.
 
 .. literalinclude:: resources/dynamic-configuration.json
     :language: json
 
-Fields have same meaning as in file configuration with only difference being Routing definition.
+Fields have the same meaning as in the configuration file with only difference being Routing definition.
+
+.. note:: There is no verification of the data correctness (e.g. if specified security files are present on machine) and thus invalid data can result in service malfunctioning or even container shutdown.
 
 Routing
 -------
 
 For every JSON key-object pair defined in **"stream_publishes"**, the key is used as domain and related object is used to setup Kafka's bootstrap servers and Kafka topic **for this domain**.
 
-Collector when receiving VES Event from client checks if domain from the event corresponds to any from Routing and publishes this event onto related topic. If there is no match, the event is dropped. If there are two routes from the same domain to different topics, then it is undefined which route will be used.
+When receiving a VES Event from client, collector checks if domain from the event corresponds to any domain from Routing and publishes this event into related topic. If there is no match, the event is dropped. If there are two routes from the same domain to different topics, then it is undefined which route is used.
 
-For more informations see :ref:`supported_domains`
+For more information, see :ref:`supported_domains`.
 
 Providing configuration during OOM deployment
 ---------------------------------------------
diff --git a/docs/sections/services/ves-hv/troubleshooting.rst b/docs/sections/services/ves-hv/troubleshooting.rst
index 5c614bbe..6b9ec8b6 100644
--- a/docs/sections/services/ves-hv/troubleshooting.rst
+++ b/docs/sections/services/ves-hv/troubleshooting.rst
@@ -28,6 +28,7 @@ For simplicity, all log messages in this section are shortened to contain only:
     * log level
     * message
 
+
 Error and warning logs contain also:
     * exception message
     * stack trace
@@ -96,6 +97,7 @@ For more information, see :ref:`run_time_configuration`
 **Invalid configuration format**
 
 ::
+
     | org.onap.dcae.services.sdk.rest.services.cbs.client.impl.CbsLookup    | INFO  | Config Binding Service address: config-binding-service:10000
     | org.onap.dcae.collectors.veshv.config.impl.CbsConfigurationProvider   | INFO  | CBS client successfully created
     | org.onap.dcae.collectors.veshv.config.impl.CbsConfigurationProvider   | INFO  | Received new configuration:
@@ -123,8 +125,8 @@ Message handling errors
     | org.onap.dcae.collectors.veshv.impl.socket.NettyTcpServer	| INFO | Connection has been close0d
 
 
-**HV-VES** responds with the above when it handles message with domain that has invalid bootstrap_servers specified in **streams_publishes** configuration.
-To fix this problem you have to correct **streams_publishes** configuration stored in Consul.
+**HV-VES** responds with the above when it handles a message with domain that has invalid bootstrap_servers specified in **streams_publishes** configuration.
+To fix this problem, you have to correct **streams_publishes** configuration stored in Consul.
 For more information, see: :ref:`run_time_configuration`.
 
 ====
@@ -132,7 +134,7 @@ For more information, see: :ref:`run_time_configuration`.
 **Kafka service became unavailable after producer has been created**
 
 **HV-VES** lazily creates Kafka producer for each domain.
-If Kafka service becomes unreachable after producer initialization, appropriate logs will be shown and **HV-VES** will fail to deliver future messages to that Kafka service.
+If Kafka service becomes unreachable after producer initialization, appropriate logs are shown and **HV-VES** fails to deliver future messages to that Kafka service.
 
 ::
 
@@ -226,10 +228,11 @@ Key or trust store password provided in configuration is invalid.
 **Empty line at the end of password file**
 
 ::
+
     | org.onap.dcae.collectors.veshv.main | ERROR | Failed to start a server | java.security.UnrecoverableKeyException: failed to decrypt safe contents entry: java.io.IOException: getSecretKey failed: Password is not ASCII
 
 
-Password file should not contain empty line at the end of the file, otherwise server startup will fail.
+Password file should not contain empty line at the end, otherwise server startup fails.
 
 ====