doc: Fix typos and improve style

siegfriedweber · siegfriedweber · commit ce184d26ed9b · 2025-07-23T10:26:54.000+02:00
diff --git a/docs/modules/opensearch/examples/getting_started/getting_started.sh b/docs/modules/opensearch/examples/getting_started/getting_started.sh
@@ -4,9 +4,6 @@ set -euo pipefail
 # DO NOT EDIT THE SCRIPT
 # Instead, update the j2 template, and regenerate it for dev with `make render-docs`.
 
-# TODO (@NickLarsenNZ): Use bitnami/postgres chart, and add version var to the above list
-# See similar changes in: https://github.com/stackabletech/hive-operator/pull/489/commits/8189f196f018c009370ae9b07a3f9609ee2e8681
-
 # This script contains all the code snippets from the guide, as well as some assert tests
 # to test if the instructions in the guide work. The user *could* use it, but it is intended
 # for testing only.
diff --git a/docs/modules/opensearch/examples/getting_started/getting_started.sh.j2 b/docs/modules/opensearch/examples/getting_started/getting_started.sh.j2
@@ -4,9 +4,6 @@ set -euo pipefail
 # DO NOT EDIT THE SCRIPT
 # Instead, update the j2 template, and regenerate it for dev with `make render-docs`.
 
-# TODO (@NickLarsenNZ): Use bitnami/postgres chart, and add version var to the above list
-# See similar changes in: https://github.com/stackabletech/hive-operator/pull/489/commits/8189f196f018c009370ae9b07a3f9609ee2e8681
-
 # This script contains all the code snippets from the guide, as well as some assert tests
 # to test if the instructions in the guide work. The user *could* use it, but it is intended
 # for testing only.
diff --git a/docs/modules/opensearch/pages/getting_started/first_steps.adoc b/docs/modules/opensearch/pages/getting_started/first_steps.adoc
@@ -1,6 +1,6 @@
 = First steps
 
-Once you have followed the steps in  xref:getting_started/installation.adoc[] for the Operator and its dependencies, you will now go through the steps to set up and connect to a OpenSearch instance.
+Once you have followed the steps in  xref:getting_started/installation.adoc[] for the operator and its dependencies, you will now go through the steps to set up and connect to a OpenSearch instance.
 
 == Security plugin configuration
 
@@ -43,7 +43,7 @@ And apply it:
 include::example$getting_started/getting_started.sh[tag=apply-cluster]
 ----
 
-`metadata.name` contains the name of the Superset cluster.
+`metadata.name` contains the name of the OpenSearch cluster.
 
 The previously created security plugin configuration must be referenced via `podOverrides`.
 
diff --git a/docs/modules/opensearch/pages/getting_started/index.adoc b/docs/modules/opensearch/pages/getting_started/index.adoc
@@ -1,7 +1,7 @@
 = Getting started
 
 This guide helps you get started with OpenSearch using the Stackable Operator.
-It covers the installation of the operator and its dependencies, setting up your first OpenSearch instance, connecting to it, and exploring sample data.
+It covers the installation of the operator and its dependencies, setting up your first OpenSearch instance, connecting to it, and ingest and search for data.
 
 == Prerequisites
 
@@ -20,5 +20,5 @@ Resource sizing depends on cluster type(s), usage and scope, but as a starting p
 
 The guide is divided into two steps:
 
-* xref:getting_started/installation.adoc[Installing the Operators].
-* xref:getting_started/first_steps.adoc[Setting up the OpenSearch instance and connecting to it].
+* xref:getting_started/installation.adoc[Installing the Operators]
+* xref:getting_started/first_steps.adoc[Setting up the OpenSearch instance and connecting to it]
diff --git a/docs/modules/opensearch/pages/getting_started/installation.adoc b/docs/modules/opensearch/pages/getting_started/installation.adoc
@@ -52,4 +52,4 @@ You are now ready to deploy OpenSearch in Kubernetes.
 
 == What's next
 
-xref:getting_started/first_steps.adoc[Deploy an OpenSearch instance and connect to it].
+xref:getting_started/first_steps.adoc[Deploy an OpenSearch instance and connect to it]
diff --git a/docs/modules/opensearch/pages/index.adoc b/docs/modules/opensearch/pages/index.adoc
@@ -20,7 +20,7 @@ This operator helps you manage your OpenSearch instances on Kubernetes efficient
 == Getting started
 
 Get started using OpenSearch with the Stackable operator by following the xref:getting_started/index.adoc[].
-It guides you through installing the operator, connecting to your OpenSearch instance and analyzing some preloaded example data.
+It guides you through installing the operator, connecting to your OpenSearch instance and using the REST API to ingest and search for data.
 
 == Operator model
 
@@ -30,7 +30,7 @@ It creates a number of different Kubernetes resources based on this {crs}[custom
 === Custom resources
 
 The OpenSearchCluster is the resource for the configuration of the OpenSearch instance.
-The resource defines only one xref:concepts:roles-and-role-groups.adoc[role], the `nodes`.
+The resource defines only one xref:concepts:roles-and-role-groups.adoc#roles[role], the `nodes`.
 The various configuration options are explained in the xref:usage-guide/index.adoc[].
 It helps you tune your cluster to your needs by configuring xref:usage-guide/storage-resource-configuration.adoc[resource usage] and more.
 
@@ -42,10 +42,10 @@ image::opensearch_overview.drawio.svg[A diagram depicting the Kubernetes resourc
 
 The diagram above depicts all the Kubernetes resources created by the operator, and how they relate to each other.
 
-For every xref:concepts:roles-and-role-groups.adoc#_role_groups[role group] you define, the operator creates a StatefulSet with the amount of replicas defined in the RoleGroup.
-For every RoleGroup, a Service is created, as well as one for the whole cluster that references the cluster manager nodes.
+For every xref:concepts:roles-and-role-groups.adoc#role-groups[role group] you define, the operator creates a StatefulSet with the amount of replicas defined in the role group.
+For every role group, a Service is created, as well as one for the whole cluster that references the cluster manager nodes.
 
-Additionally, a ConfigMap is created for each RoleGroup.
+Additionally, a ConfigMap is created for each role group.
 These ConfigMaps contain configuration files like `opensearch.yml`.
 
 == Supported versions
diff --git a/docs/modules/opensearch/pages/reference/crds.adoc b/docs/modules/opensearch/pages/reference/crds.adoc
@@ -1,3 +1,3 @@
 = CRD Reference
 
-Find all CRD reference for the Stackable Operator for OpenSearch at: {crd-docs-base-url}/opensearch-operator/{crd-docs-version}.
+Find all CRD references for the Stackable Operator for OpenSearch at: {crd-docs-base-url}/opensearch-operator/{crd-docs-version}
diff --git a/docs/modules/opensearch/pages/reference/environment-variables.adoc b/docs/modules/opensearch/pages/reference/environment-variables.adoc
@@ -33,32 +33,6 @@ docker run \
 oci.stackable.tech/sdp/opensearch-operator:0.0.0-dev
 ----
 
-== PRODUCT_CONFIG
-
-*Default value*: `/etc/stackable/opensearch-operator/config-spec/properties.yaml`
-
-*Required*: false
-
-*Multiple values*: false
-
-[source]
-----
-export PRODUCT_CONFIG=/foo/bar/properties.yaml
-stackable-opensearch-operator run
-----
-
-or via docker:
-
-----
-docker run \
-    --name opensearch-operator \
-    --network host \
-    --env KUBECONFIG=/home/stackable/.kube/config \
-    --env PRODUCT_CONFIG=/my/product/config.yaml \
-    --mount type=bind,source="$HOME/.kube/config",target="/home/stackable/.kube/config" \
-    oci.stackable.tech/sdp/opensearch-operator:0.0.0-dev
-----
-
 == WATCH_NAMESPACE
 
 *Default value*: All namespaces
diff --git a/docs/modules/opensearch/pages/usage-guide/configuration-environment-overrides.adoc b/docs/modules/opensearch/pages/usage-guide/configuration-environment-overrides.adoc
@@ -9,7 +9,7 @@ IMPORTANT: Overriding certain properties which are set by the operator (such as
 == Configuration Properties
 
 For a role or role group, at the same level of `config`, you can specify `configOverrides` for the `opensearch.yml`.
-For example, if you want to enable role-based access to the REST management API for the role `all_access`, then adapt the `nodes` section of the cluster resource as follows:
+For example, if you want to enable role-based access to the REST management API for the role `all_access`, then adapt the cluster resource as follows:
 
 [source,yaml]
 ----
diff --git a/docs/modules/opensearch/pages/usage-guide/index.adoc b/docs/modules/opensearch/pages/usage-guide/index.adoc
@@ -2,6 +2,6 @@
 :page-aliases: usage.doc
 :description: OpenSearch usage guide: configure resources and override configurations.
 
-The usage guide covers various aspects of configuring OpenSearch and interconnection with other tools.
+The usage guide covers various aspects of configuring OpenSearch.
 
 Learn about xref:usage-guide/node-roles.adoc[] or defining the amount of xref:usage-guide/storage-resource-configuration.adoc[resources] OpenSearch uses.
diff --git a/docs/modules/opensearch/pages/usage-guide/node-roles.adoc b/docs/modules/opensearch/pages/usage-guide/node-roles.adoc
@@ -4,7 +4,7 @@
 An OpenSearch node can fulfill different roles, e.g. it can manage the operation of a cluster or store and search data.
 
 All nodes are defined under the role `nodes`.
-The role config already defaults to a set of node roles:
+The role configuration already defaults to a set of node roles:
 
 [source,yaml]
 ----
@@ -65,4 +65,4 @@ The following roles are currently supported by the operator:
 * `search`
 * `warm`
 
-We refer to https://docs.opensearch.org/docs/latest/install-and-configure/configuring-opensearch/configuration-system/[the OpenSearch documentation] for an exlanation of the roles.
+We refer to https://docs.opensearch.org/docs/latest/install-and-configure/configuring-opensearch/configuration-system/[the OpenSearch documentation] for an explanation of the roles.
diff --git a/docs/modules/opensearch/pages/usage-guide/operations/pod-disruptions.adoc b/docs/modules/opensearch/pages/usage-guide/operations/pod-disruptions.adoc
@@ -6,4 +6,4 @@ Unless you configure something else or disable the provided PodDisruptionBudgets
 
 == Nodes
 
-The provided PDBs only allow a single node to be offline at any given time, regardless of the number of replicas or `roleGroups`.
+The provided PDBs only allow a single node to be offline at any given time, regardless of the number of replicas or role groups.
diff --git a/docs/modules/opensearch/pages/usage-guide/storage-resource-configuration.adoc b/docs/modules/opensearch/pages/usage-guide/storage-resource-configuration.adoc
@@ -9,19 +9,19 @@ You can mount volumes where data is stored by specifying https://kubernetes.io/d
 ----
 nodes:
   roleGroups:
-    default:
+    data:
       config:
         resources:
           storage:
             logDirs:
               capacity: 50Gi
 ----
 
-In the above example, all OpenSearch nodes in the default role group store data (the location of the property `path.data`) on a `50Gi` volume.
+In the example above, all OpenSearch nodes in the data role group store data (the location of the property `path.data`) on a `50Gi` volume.
 
 If nothing is configured in the custom resource for a certain role group, then by default each Pod has a `8Gi` large local volume mount for the data location.
 
-On role groups with only the `cluster_manager` role, you probably want to decrease this value, but increase it on role groups with the `data` role.
+On role groups with only the `cluster_manager` node role, you probably want to decrease this value, but increase it on role groups with the `data` node role.
 
 == Resource Requests
 

Original file line number	Diff line number	Diff line change
`@@ -52,4 +52,4 @@ You are now ready to deploy OpenSearch in Kubernetes.`
`52`	`52`
`53`	`53`	`== What's next`
`54`	`54`
`55`		`-xref:getting_started/first_steps.adoc[Deploy an OpenSearch instance and connect to it].`
	`55`	`+xref:getting_started/first_steps.adoc[Deploy an OpenSearch instance and connect to it]`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,3 @@`
`1`	`1`	`= CRD Reference`
`2`	`2`
`3`		`-Find all CRD reference for the Stackable Operator for OpenSearch at: {crd-docs-base-url}/opensearch-operator/{crd-docs-version}.`
	`3`	`+Find all CRD references for the Stackable Operator for OpenSearch at: {crd-docs-base-url}/opensearch-operator/{crd-docs-version}`