[Docu] website: Documentation enhanced

Misc improvements to some documentation

website/content/en/docs/installation/helm/_index.md

@@ -10,17 +10,17 @@ description: >
 
 To install CAP operator components, we recommend using the [Helm chart](https://github.com/sap/cap-operator-lifecycle/tree/main/chart) that is published as an OCI package at `oci://ghcr.io/sap/cap-operator-lifecycle/helm/cap-operator`.
 
-### Installation
+## Installation
 
 Create a namespace and install the Helm chart in that namespace by specifying the `domain` and the `dnsTarget` for your subscription server, either 
 
-- #### As command line parameters:
+- ### As command line parameters:
   ```bash
   kubectl create namespace cap-operator-system
   helm upgrade -i -n cap-operator-system cap-operator oci://ghcr.io/sap/cap-operator-lifecycle/helm/cap-operator --set subscriptionServer.domain=cap-operator.<CLUSTER-DOMAIN> --set subscriptionServer.dnsTarget=public-ingress.<CLUSTER-DOMAIN>
   ```
 
-- #### Or as a `YAML` file with the values:
+- ### Or as a `YAML` file with the values:
   ```bash
   kubectl create namespace cap-operator-system
   helm upgrade -i -n cap-operator-system cap-operator oci://ghcr.io/sap/cap-operator-lifecycle/helm/cap-operator -f my-cap-operator-values.yaml
@@ -32,9 +32,9 @@ Create a namespace and install the Helm chart in that namespace by specifying th
     domain: cap-operator.<CLUSTER-DOMAIN>   
   ```
 
-### Optional steps
+## Optional steps
 
-- #### Enable Service Monitors for metrics emitted by controller and subscription server
+- ### Enable Service Monitors for metrics emitted by controller and subscription server
 
   To enable Monitoring via [metrics](docs/usage/operator-metrics) emitted by CAP Operator components, the following value can be specified:
   ```yaml
@@ -46,7 +46,7 @@ Create a namespace and install the Helm chart in that namespace by specifying th
   controller:
       detailedOperationalMetrics: true
   ```
-- #### Setup Prometheus Integration for _Version Monitoring_
+- ### Setup Prometheus Integration for _Version Monitoring_
 
   To use the [Version Monitoring](docs/usage/version-monitoring/) feature of the CAP Operator, a [Prometheus](https://prometheus.io/) server URL can be provided to the CAP Operator. When installing the CAP Operator using the Helm chart, the following values can be specified in the values:
   ```yaml

website/content/en/docs/usage/operator-metrics.md

@@ -7,56 +7,74 @@ description: >
   How to monitor and consume metrics emitted by CAP Operator
 ---
 
-The [Controller](docs/concepts/operator-components/controller/) and [Subscription Server](docs/concepts/operator-components/subscription-server/) now emit [Prometheus metrics](https://pkg.go.dev/github.com/prometheus/client_golang/prometheus) at `/metrics` path and `9090` port that may be used by consumers to analyze and understand usage, detect potential issues, monitor and scale cluster resources.
-You can enable
+## Overview
 
-### Controller metrics
-The controller emits [standard go metrics](https://pkg.go.dev/github.com/prometheus/client_golang/prometheus/collectors#WithGoCollectorRuntimeMetrics), workqueue metrics for the resources being reconciled implemented based on [MetricsProvider](https://pkg.go.dev/k8s.io/client-go/util/workqueue#MetricsProvider) and the following additional metrics:
+The CAP Operator includes built-in [Prometheus metrics](https://pkg.go.dev/github.com/prometheus/client_golang/prometheus) that enable users to effectively monitor and analyze the operator's performance. These metrics can provide insights into resource usage, potential issues, and overall operator health. The metrics are accessible at the `/metrics` endpoint on port `9090` of both the [Controller](docs/concepts/operator-components/controller/) and the [Subscription Server](docs/concepts/operator-components/subscription-server/).
 
-{{% pageinfo %}}
+## Controller Metrics
+
+The Controller emits several types of metrics, including:
+
+- **Standard Go Metrics**: These metrics are provided by the [Prometheus Go client](https://pkg.go.dev/github.com/prometheus/client_golang/prometheus/collectors#WithGoCollectorRuntimeMetrics) and include runtime statistics.
+- **Workqueue Metrics**: These metrics are relevant to the resources being reconciled and are based on the [MetricsProvider](https://pkg.go.dev/k8s.io/client-go/util/workqueue#MetricsProvider).
+- Specific metrics: [mentioned below](#specific-metrics).
+
+### Specific Metrics
+
+1. **Reconcile Errors** -- `cap_op_reconcile_errors`, e.g.:
 ```
 cap_op_reconcile_errors{kind="CAPApplication",name="my-app",namespace="app"} 11
 ```
-a counter type metric indicating total resources that failed to reconcile for each Kind.
-
----
+- **Type**: Counter
+- **Description**: This metric tracks the total number of resources that failed to reconcile for each resource kind, such as `CAPApplication`.
 
+2. **Tenant Operations** -- `cap_op_tenant_operations`, e.g.
 ```
 cap_op_tenant_operations{app="<hash>",operation="provisioning"} 83
 ```
-a counter type metric that provides some insights into the overall number of tenant operations.
-{{% /pageinfo %}}
+- **Type**: Counter
+- **Description**: This metric provides insights into overall tenant operations being performed.
+
+### Detailed Operational Metrics
 
-By setting the enviroment variable `DETAILED_OPERATIONAL_METRICS` to `"true"`, one can optionally also see these detailed operational metrics:
+To gain deeper insights, you can enable more granular metrics by setting the environment variable `DETAILED_OPERATIONAL_METRICS` to `"true"`.
 
-{{% pageinfo %}}
+1. **Failed Tenant Operations** -- `cap_op_tenant_operation_failures`, e.g.:
 ```
 cap_op_tenant_operation_failures{app="<hash>",operation="upgrade",tenant_id="<guid>",namespace="app",name="my-app-tenant-op-xxyyz"} 2
 ```
-a counter type metric that provides some insights into failed tenant operations per app, tenant along with name and namespace details of the failed operation resource.
-
----
+- **Type**: Counter
+- **Description**: This metric reveals the number of failed tenant operations, categorized by application, tenant ID, and specific operation details.
 
+2. **Last Tenant Operation Duration** -- `cap_op_last_tenant_operation_duration_seconds`, e.g.:
 ```
-cap_op_last_tenant_operation_duration_seconds{app="<hash>",tenant_id="<guid>"} 42
+cap_op_last_tenant_operation_duration_seconds{app="<hash>",tenant_id="<guid>"} 17
 ```
-a guage type metric that provides some info about the duration in seconds taken by the last tenant operation for an app and tenant.
-{{% /pageinfo %}}
+- **Type**: Gauge
+- **Description**: This metric measures the duration (in seconds) of the last tenant operation for a specified application and tenant.
 
+## Subscription Server Metrics
 
-### Subscription Server metrics
-The controller emits [standard go metrics](https://pkg.go.dev/github.com/prometheus/client_golang/prometheus/collectors#WithGoCollectorRuntimeMetrics), and the following http handler specific metrics:
+The Subscription Server emits the following metrics:
+- **Standard Go Metrics**: These metrics are provided by the [Prometheus Go client](https://pkg.go.dev/github.com/prometheus/client_golang/prometheus/collectors#WithGoCollectorRuntimeMetrics) and include runtime statistics.
+- Specific metrics: [mentioned below](#specific-metrics-1).
 
-{{% pageinfo %}}
+### Specific Metrics
+
+1. **Subscription Requests Total** -- `cap_op_subscription_requests_total`, e.g.:
 ```
-cap_op_subscription_requests_total{code="202",method="POST"} 82
+cap_op_subscription_requests_total{code="202",method="POST"} 2024
 ```
-a counter type metric indicating total requests triggered for susbscription based on http method and response code.
-
----
+- **Type**: Counter
+- **Description**: This metric tracks the total number of subscription requests that were processed, categorized by HTTP method and response code.
 
+2. **Inflight Subscription Requests** -- `cap_op_subscription_requests_inflight`, e.g.:
 ```
-cap_op_subscription_requests_inflight{} 1
+cap_op_subscription_requests_inflight{} 4
 ```
-a guage type metric indicating the subscription requests currently being processed by the handler.
-{{% /pageinfo %}}
+- **Type**: Gauge
+- **Description**: This metric indicates the number of subscription requests currently being processed by the server.
+
+## Conclusion
+
+The CAP Operator provides a rich set of metrics to facilitate monitoring and operational insights. By effectively leveraging these metrics, you can monitor and ensure the reliability and performance of your applications. For further details, consider exploring the Prometheus documentation and integrating these metrics into your monitoring systems.

website/content/en/docs/usage/prerequisites.md

@@ -7,19 +7,19 @@ description: >
   What to do before you deploy a new CAP application
 ---
 
-### Prepare the SAP BTP global account and provider subaccount
+## Prepare the SAP BTP global account and provider subaccount
 
 CAP-based applications make use of various SAP BTP services that are created in a provider subaccount. So, before you can deploy the application, create a global account and assign the required services that will be used. To do so, use [SAP BTP Control Center](https://controlcenter.ondemand.com/index.html). Once done, create a provider subaccount, where the required service instances can be created.
 
-### Create service instances and bindings
+## Create service instances and bindings
 
 A multi-tenant CAP-based application consumes the following SAP BTP services. While creating these service instances, some of the parameters supplied require special attention. Service keys (bindings) are then created to generate access credentials, which in turn should be provided as Kubernetes Secrets in the namespace where the application is being deployed.
 
 Other services (not listed here) may also be used depending on the requirement (for example, SAP HTML5 Application Repository service for SAP BTP, Business Logging, and so on).
 
 > Note: If some SAP BTP services are not available on Kubernetes, enable Cloud Foundry for the provider subaccount to create certain services. In such cases you may use the [cf-service-operator](https://sap.github.io/cf-service-operator/docs/) for managing the service instances and service bindings directly from within the Kubernetes cluster. Based on the service bindings, it automatically generates the secrets containing the service access credentials.
 
-##### SAP Authorization and Trust Management Service
+### SAP Authorization and Trust Management Service
 
 The parameter `oauth2-configuration.redirect-uris` must include the domain used by the application. For instance, if the application is hosted in a "Gardener"  managed cluster, the entry may have the form `https://*<application-specific-prefix>.<cluster-id>.<gardener-project-id>.shoot.url.k8s.example.com/**`.
 
@@ -81,7 +81,7 @@ spec:
   ...
 ```
 
-##### SAP Software-as-a-Service Provisioning service
+### SAP Software-as-a-Service Provisioning service
 
 When creating an instance of the SaaS Provisioning service, use asynchronous tenant subscription callbacks in the configuration. See [Register Your Multi-Tenant Application/Service in SaaS Provisioning](https://controlcenter.ondemand.com/index.html#/knowledge_center/articles/f239e5501a534b64ab5f8dde9bd83c53) for more details.
 
@@ -96,10 +96,10 @@ parameters:
     onUnSubscriptionAsync: true
 ```
 
-##### SAP HANA Cloud
+### SAP HANA Cloud
 
 An SAP HANA Cloud instance (preferably shared and accessible from the provider subaccount) is required. The Instance ID of the database must be noted for usage in relevant workloads. SAP HANA Schemas & HDI Containers service must also be entitled for the provider subaccount.
 
-#####  SAP Service Manager service
+###  SAP Service Manager service
 
 The SAP Service Manager service allows CAP to retrieve schema-(tenant-)specific credentials to connect to the SAP HANA Cloud database.

website/content/en/docs/whats-new.md

@@ -18,12 +18,6 @@ description: >
   {{% card header="Q3 2024" %}}
   New Custom Resource `CAPTenantOutput` can be used to record subscription related data from tenant operations. [Learn more](./usage/resources/captenantoutput.md).
   {{% /card %}}
-{{% /cardpane %}}
-
-
-### Previous updates
-
-{{% cardpane %}}
   {{% card header="Q2 2024" %}}
   `CAPApplicationVersion` now supports configuration of `initContainers`, `volumes`, `serviceAccountName`, [scheduling related configurations](https://kubernetes.io/docs/concepts/scheduling-eviction/) etc. on workloads.
   {{% /card %}}