docs: pod overrides, better install instructions, improved wording (#569)

* ~

* Update docs/modules/hbase/pages/getting_started/installation.adoc

* Update docs/modules/hbase/pages/usage-guide/operations/graceful-shutdown.adoc

* Update docs/modules/hbase/pages/usage-guide/operations/pod-placement.adoc

* Update docs/modules/hbase/pages/usage-guide/security.adoc

* fix: spelling

---------

Co-authored-by: Razvan-Daniel Mihai <84674+razvan@users.noreply.github.com>

Author: fhennig

docs/modules/hbase/pages/getting_started/first_steps.adoc

@@ -2,8 +2,8 @@
 :description: Deploy and verify an HBase cluster using ZooKeeper, HDFS, and HBase configurations. Test with REST API and Apache Phoenix for table creation and data querying.
 :phoenix: https://phoenix.apache.org/index.html
 
-Once you have followed the steps in the xref:getting_started/installation.adoc[] section to install the operator and its dependencies, you will now deploy an HBase cluster and its dependencies.
-Afterwards you can <<_verify_that_it_works, verify that it works>> by creating tables and data in HBase using the REST API and Apache Phoenix (an SQL layer used to interact with HBase).
+Once you have followed the steps in the xref:getting_started/installation.adoc[] section to install the operator and its dependencies, you deploy an HBase cluster and its dependencies.
+Afterward you can <<_verify_that_it_works, verify that it works>> by creating tables and data in HBase using the REST API and Apache Phoenix (an SQL layer used to interact with HBase).
 
 == Setup
 
@@ -14,7 +14,7 @@ To deploy a ZooKeeper cluster create one file called `zk.yaml`:
 [source,yaml]
 include::example$getting_started/zk.yaml[]
 
-We also need to define a ZNode that will be used by the HDFS and HBase clusters to reference ZooKeeper.
+We also need to define a ZNode that is used by the HDFS and HBase clusters to reference ZooKeeper.
 Create another file called `znode.yaml` and define a separate ZNode for each service:
 
 [source,yaml]
@@ -73,16 +73,16 @@ include::example$getting_started/hbase.yaml[]
 
 == Verify that it works
 
-To test the cluster you will use the REST API to check its version and status, and to create and inspect a new table.
-You will also use Phoenix to create, populate and query a second new table, before listing all non-system tables in HBase.
+To test the cluster, use the REST API to check its version and status, and to create and inspect a new table.
+Use Phoenix to create, populate and query a second new table, before listing all non-system tables in HBase.
 These actions wil be carried out from one of the HBase components, the REST server.
 
 First, check the cluster version with this callout:
 
 [source]
 include::example$getting_started/getting_started.sh[tag=cluster-version]
 
-This will return the version that was specified in the HBase cluster definition:
+This returns the version that was specified in the HBase cluster definition:
 
 [source,json]
 {"Version":"2.4.18"}
@@ -92,7 +92,7 @@ The cluster status can be checked and formatted like this:
 [source]
 include::example$getting_started/getting_started.sh[tag=cluster-status]
 
-which will display cluster metadata that looks like this (only the first region is included for the sake of readability):
+which displays cluster metadata that looks like this (only the first region is included for the sake of readability):
 
 [source,json]
 {
@@ -134,7 +134,7 @@ You can now create a table like this:
 [source]
 include::example$getting_started/getting_started.sh[tag=create-table]
 
-This will create a table `users` with a single column family `cf`.
+This creates a table `users` with a single column family `cf`.
 Its creation can be verified by listing it:
 
 [source]
@@ -155,7 +155,7 @@ Use the Python utility `psql.py` (found in /stackable/phoenix/bin) to create, po
 [source]
 include::example$getting_started/getting_started.sh[tag=phoenix-table]
 
-The final command will display some grouped data like this:
+The final command displays some grouped data like this:
 
 [source]
 HO                    TOTAL_ACTIVE_VISITORS

docs/modules/hbase/pages/getting_started/index.adoc

@@ -1,6 +1,6 @@
 = Getting started
 
-This guide will get you started with HBase using the Stackable operator.
+This guide gets you started with HBase using the Stackable operator.
 It guides you through the installation of the operator and its dependencies, setting up your first HBase cluster and verifying its operation.
 
 == Prerequisites

docs/modules/hbase/pages/getting_started/installation.adoc

@@ -2,17 +2,17 @@
 :description: Install Stackable HBase and required operators using stackablectl or Helm on Kubernetes. Follow setup and verification steps for a complete installation.
 :kind: https://kind.sigs.k8s.io/
 
-On this page you will install the Stackable HBase operator and its dependencies, the ZooKeeper and HDFS operators, as well as the commons, secret and listener operators which are required by all Stackable operators.
+Install the Stackable HBase operator and its dependencies, the ZooKeeper and HDFS operators, as well as the commons, secret and listener operators which are required by all Stackable operators.
 
-== Stackable Operators
-
-There are 2 ways to run Stackable operators
-
-. Using xref:management:stackablectl:index.adoc[]
-. Using Helm
-
-=== stackablectl
+There are multiple ways to install the Stackable Operator for Apache Zookeeper.
+xref:management:stackablectl:index.adoc[] is the preferred way, but Helm is also supported.
+OpenShift users may prefer installing the operator from the RedHat Certified Operator catalog using the OpenShift web console.
 
+[tabs]
+====
+stackablectl::
++
+--
 `stackablectl` is the command line tool to interact with Stackable operators and our recommended way to install operators.
 Follow the xref:management:stackablectl:installation.adoc[installation steps] for your platform.
 
@@ -23,32 +23,34 @@ After you have installed stackablectl run the following command to install all o
 include::example$getting_started/getting_started.sh[tag=stackablectl-install-operators]
 ----
 
-The tool will show
+The tool shows
 
 [source]
 include::example$getting_started/install_output.txt[]
 
 
 TIP: Consult the xref:management:stackablectl:quickstart.adoc[] to learn more about how to use `stackablectl`.
 For example, you can use the `--cluster kind` flag to create a Kubernetes cluster with {kind}[kind].
+--
 
-=== Helm
-
-You can also use Helm to install the operators.
+Helm::
++
+--
 Add the Stackable Helm repository:
 [source,bash]
 ----
 include::example$getting_started/getting_started.sh[tag=helm-add-repo]
 ----
 
-Then install the Stackable Operators:
+Install the Stackable operators:
 [source,bash]
 ----
 include::example$getting_started/getting_started.sh[tag=helm-install-operators]
 ----
 
-Helm will deploy the operators in a Kubernetes Deployment and apply the CRDs for the HBase cluster (as well as the CRDs for the required operators).
-You are now ready to deploy HBase in Kubernetes.
+Helm deploys the operators in a Kubernetes Deployment and apply the CRDs for the HBase cluster (as well as the CRDs for the required operators).
+--
+====
 
 == What's next
 

docs/modules/hbase/pages/index.adoc

@@ -18,7 +18,7 @@ Apache HBase is an open-source, distributed, non-relational database that runs o
 == Getting started
 
 Follow the xref:getting_started/index.adoc[] guide to learn how to xref:getting_started/installation.adoc[install] the Stackable operator for Apache HBase as well as the dependencies.
-The guide will also show you how to xref:getting_started/first_steps.adoc[interact] with HBase running on Kubernetes by creating tables and some data using the REST API or Apache Phoenix.
+The guide shows you how to xref:getting_started/first_steps.adoc[interact] with HBase running on Kubernetes by creating tables and some data using the REST API or Apache Phoenix.
 
 The xref:usage-guide/index.adoc[] contains more information on xref:usage-guide/phoenix.adoc[] as well as other topics
 such as xref:usage-guide/resource-requests.adoc[CPU and memory configuration], xref:usage-guide/monitoring.adoc[] and
@@ -55,7 +55,7 @@ The xref:demos:hbase-hdfs-load-cycling-data.adoc[] demo shows how you can use HB
 == Supported versions
 
 The Stackable operator for Apache HBase currently supports the HBase versions listed below.
-To use a specific HBase version in your HBaseCluster, you have to specify an image - this is explained in the xref:concepts:product-image-selection.adoc[] documentation.
+To use a specific HBase version in your HBaseCluster, you have to specify an image -- this is explained in the xref:concepts:product-image-selection.adoc[] documentation.
 The operator also supports running images from a custom registry or running entirely customized images; both of these cases are explained under xref:concepts:product-image-selection.adoc[] as well.
 
 include::partial$supported-versions.adoc[]

docs/modules/hbase/pages/reference/commandline-parameters.adoc

@@ -23,7 +23,7 @@ stackable-hbase-operator run --product-config /foo/bar/properties.yaml
 
 *Multiple values:* false
 
-The operator will **only** watch for resources in the provided namespace `test`:
+The operator **only** watches for resources in the provided namespace `test`:
 
 [source]
 ----

docs/modules/hbase/pages/reference/environment-variables.adoc

@@ -36,7 +36,7 @@ docker run \
 
 *Multiple values:* false
 
-The operator will **only** watch for resources in the provided namespace `test`:
+The operator **only** watches for resources in the provided namespace `test`:
 
 [source]
 ----

docs/modules/hbase/pages/usage-guide/operations/graceful-shutdown.adoc

@@ -6,8 +6,8 @@ You can configure the graceful shutdown as described in xref:concepts:operations
 
 As a default, masters have `20 minutes` to shut down gracefully.
 
-The HBase master process will receive a `SIGTERM` signal when Kubernetes wants to terminate the Pod.
-After the graceful shutdown timeout runs out, and the process still didn't exit, Kubernetes will issue a `SIGKILL` signal.
+The HBase master process receives a `SIGTERM` signal when Kubernetes wants to terminate the Pod.
+After the graceful shutdown timeout runs out, and the process is still running, Kubernetes issues a `SIGKILL` signal.
 
 This is equivalent to executing the `bin/hbase-daemon.sh stop master` command, which internally executes `kill <master-pid>` (https://github.com/apache/hbase/blob/8382f55b15be6ae190f8d202a5e6a40af177ec76/bin/hbase-daemon.sh#L338[code]), waits for a configurable period of time (defaults to 20 minutes), and finally executes `kill -9 <master-pid>` to `SIGKILL` the master (https://github.com/apache/hbase/blob/8382f55b15be6ae190f8d202a5e6a40af177ec76/bin/hbase-common.sh#L20-L41[code]).
 

docs/modules/hbase/pages/usage-guide/operations/pod-placement.adoc

@@ -106,7 +106,7 @@ In the examples above `cluster-name` is the name of the HBase custom resource th
 The `hdfs-cluster-name` is the name of the HDFS cluster that was configured in the `hdfsConfigMapName` property.
 
 NOTE: It is important that the `hdfsConfigMapName` property contains the name the HDFS cluster.
-You could instead configure ConfigMaps of specific name or data roles, but for the purpose of pod placement, this will lead to faulty behavior.
+You could instead configure ConfigMaps of specific name or data roles, but for the purpose of Pod placement, this leads to faulty behavior.
 
 == Use custom pod placement
 For general configuration of Pod placement, see the xref:concepts:operations/pod_placement.adoc[Pod placement concepts] page.
@@ -131,4 +131,4 @@ spec:
         replicas: 2
 ----
 
-WARNING: Please note that the Pods will be stuck in `Pending`, when your Kubernetes cluster does not have any node without a masters already running on it and sufficient compute resources.
+WARNING: The Pods remain in the  `Pending` phase until the masters are up and running and there are  sufficient compute resources available.

docs/modules/hbase/pages/usage-guide/overrides.adoc

@@ -4,15 +4,15 @@
 
 The HBase xref:concepts:stacklet.adoc[Stacklet] definition also supports overriding configuration properties, environment variables and Pod specs, either per role or per role group, where the more specific override (role group) has precedence over the less specific one (role).
 
-IMPORTANT: Overriding certain properties which are set by operator can interfere with the operator and can lead to problems.
+IMPORTANT: Overriding operator-set properties can interfere with the operator and can lead to problems.
 
 == Configuration properties
 
 For a role or role group, at the same level of `config`, you can specify: `configOverrides` for the following files:
 
-- `hbase-site.xml`
-- `hbase-env.sh`
-- `security.properties`
+* `hbase-site.xml`
+* `hbase-env.sh`
+* `security.properties`
 
 NOTE: `hdfs-site.xml` is not listed here, the file is always taken from the referenced HDFS cluster.
 If you want to modify it, take a look at xref:hdfs:usage-guide/configuration-environment-overrides.adoc[HDFS configuration overrides].
@@ -33,7 +33,7 @@ restServers:
       replicas: 1
 ----
 
-Just as for the `config`, it is possible to specify this at role level as well:
+Just as for the `config`, you can specify this at role level as well:
 
 [source,yaml]
 ----
@@ -50,7 +50,7 @@ restServers:
 ----
 
 All override property values must be strings.
-The properties will be formatted and escaped correctly into the XML file, respectively inserted as is into the `hbase-env.sh` file.
+The properties are formatted and escaped correctly into the XML file, respectively inserted as is into the `hbase-env.sh` file.
 
 For a full list of configuration options we refer to the HBase https://hbase.apache.org/book.html#config.files[configuration documentation].
 

docs/modules/hbase/pages/usage-guide/phoenix.adoc

@@ -4,7 +4,7 @@
 :sqlline-github: https://github.com/julianhyde/sqlline
 
 Apache Phoenix allows you to interact with HBase using a familiar SQL-syntax via a JDBC driver.
-The Phoenix dependencies are bundled with the Stackable HBase image and do not need to be installed separately (client components will need to ensure that they have the correct client-side libraries available).
+The Phoenix dependencies are bundled with the Stackable HBase image and do not need to be installed separately (client components need to ensure that they have the correct client-side libraries available).
 Information about client-side installation can be found {phoenix-installation}[here].
 
 Apache Phoenix comes bundled with a few simple scripts to verify a correct server-side installation.