retro docs review (#4305)

* retro docs review * Update docs/self-managed/concepts/multi-region/dual-region.md Co-authored-by: Cole Isaac <82131455+conceptualshark@users.noreply.github.com> * adjust localhost links * Update docs/self-managed/concepts/multi-region/dual-region.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --------- Co-authored-by: Cole Isaac <82131455+conceptualshark@users.noreply.github.com> Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
camunda · Sep 26, 2024 · f9794c5 · f9794c5
1 parent 1f8534e
commit f9794c5
Show file tree

Hide file tree

Showing 17 changed files with 113 additions and 117 deletions.
diff --git a/docs/components/modeler/bpmn/business-rule-tasks/business-rule-tasks.md b/docs/components/modeler/bpmn/business-rule-tasks/business-rule-tasks.md
@@ -44,9 +44,9 @@ a `string`.
 
 The `bindingType` attribute determines which version of the called decision is evaluated:
 
-- `latest`: the latest deployed version at the moment the business rule task is activated.
-- `deployment`: the version that was deployed together with the currently running version of the process.
-- `versionTag`: the latest deployed version that is annotated with the version tag specified in the `versionTag` attribute.
+- `latest`: The latest deployed version at the moment the business rule task is activated.
+- `deployment`: The version that was deployed together with the currently running version of the process.
+- `versionTag`: The latest deployed version that is annotated with the version tag specified in the `versionTag` attribute.
 
 To learn more about choosing binding types, see [Choosing the resource binding type](/docs/components/best-practices/modeling/choosing-the-resource-binding-type.md).
 

diff --git a/docs/components/modeler/bpmn/call-activities/call-activities.md b/docs/components/modeler/bpmn/call-activities/call-activities.md
@@ -20,9 +20,9 @@ Usually, the `processId` is defined as a [static value](/components/concepts/exp
 
 The `bindingType` attribute determines which version of the called process is instantiated:
 
-- `latest`: the latest deployed version at the moment the call activity is activated.
-- `deployment`: the version that was deployed together with the currently running version of the calling process.
-- `versionTag`: the latest deployed version that is annotated with the version tag specified in the `versionTag` attribute.
+- `latest`: The latest deployed version at the moment the call activity is activated.
+- `deployment`: The version that was deployed together with the currently running version of the calling process.
+- `versionTag`: The latest deployed version that is annotated with the version tag specified in the `versionTag` attribute.
 
 To learn more about choosing binding types, see [Choosing the resource binding type](/docs/components/best-practices/modeling/choosing-the-resource-binding-type.md).
 

diff --git a/docs/components/modeler/bpmn/user-tasks/user-tasks.md b/docs/components/modeler/bpmn/user-tasks/user-tasks.md
@@ -121,9 +121,9 @@ Depending on your use case, two different types of form references can be used:
 
    The `bindingType` attribute determines which version of the linked form is used:
 
-   - `latest`: the latest deployed version at the moment the user task is activated.
-   - `deployment`: the version that was deployed together with the currently running version of the process.
-   - `versionTag`: the latest deployed version that is annotated with the version tag specified in the `versionTag` attribute.
+   - `latest`: The latest deployed version at the moment the user task is activated.
+   - `deployment`: The version that was deployed together with the currently running version of the process.
+   - `versionTag`: The latest deployed version that is annotated with the version tag specified in the `versionTag` attribute.
 
    To learn more about choosing binding types, see [Choosing the resource binding type](/docs/components/best-practices/modeling/choosing-the-resource-binding-type.md).
 

diff --git a/.../components/modeler/web-modeler/advanced-modeling/business-rule-task-linking.md b/.../components/modeler/web-modeler/advanced-modeling/business-rule-task-linking.md
@@ -26,8 +26,8 @@ For business rule tasks that are already linked, clicking on the link icon opens
 
 You can also enter the Decision ID directly in the **Called decision** section in the properties panel after selecting **DMN decision** for the **Implementation**.
 
-- **Binding**: You can also select a different Binding for the called decision. See [Choosing the resource binding type](/docs/components/best-practices/modeling/choosing-the-resource-binding-type.md).
-- **Version tag**: If you select **version tag** for the Binding, you must enter the actual version tag to use.
+- **Binding**: You can also select a different binding for the called decision. See [choosing the resource binding type](/docs/components/best-practices/modeling/choosing-the-resource-binding-type.md).
+- **Version tag**: If you select **version tag** for the binding, you must enter the actual version tag to use.
 
 <p><img src={PropertiesPanelImg} alt="called decision section in properties panel" style={{width: 430}} /></p>
 

diff --git a/docs/components/modeler/web-modeler/advanced-modeling/call-activity-linking.md b/docs/components/modeler/web-modeler/advanced-modeling/call-activity-linking.md
@@ -24,8 +24,8 @@ For call activities that are already linked, clicking on the link button opens a
 
 You can also enter the process ID directly in the **Called element** section in the properties panel.
 
-- **Binding**: You can also select a different Binding for the called decision. See [Choosing the resource binding type](/docs/components/best-practices/modeling/choosing-the-resource-binding-type.md).
-- **Version tag**: If you select **version tag** for the Binding, you must enter the actual version tag to use.
+- **Binding**: You can also select a different binding for the called decision. See [choosing the resource binding type](/docs/components/best-practices/modeling/choosing-the-resource-binding-type.md).
+- **Version tag**: If you select **version tag** for the binding, you must enter the actual version tag to use.
 
 <p><img src={PropertiesPanelImg} alt="called element section in properties panel" style={{width: 430}} /></p>
 

diff --git a/docs/components/modeler/web-modeler/advanced-modeling/form-linking.md b/docs/components/modeler/web-modeler/advanced-modeling/form-linking.md
@@ -38,10 +38,10 @@ Using the properties panel, you can connect a form to a user task/start event vi
 
 ### Camunda Form (linked)
 
-Choosing **Camunda Form (linked)** as the type and entering the form ID directly, produces the same result as [using the link button on the modeling canvas](#using-the-link-button).
+Choosing **Camunda Form (linked)** as the type and entering the form ID directly produces the same result as [using the link button on the modeling canvas](#using-the-link-button).
 
-- **Binding**: You can also select a different Binding for the linked form. See [Choosing the resource binding type](/docs/components/best-practices/modeling/choosing-the-resource-binding-type.md).
-- **Version tag**: If you select **version tag** for the Binding, you must enter the actual version tag to use.
+- **Binding**: You can also select a different binding for the called decision. See [choosing the resource binding type](/docs/components/best-practices/modeling/choosing-the-resource-binding-type.md).
+- **Version tag**: If you select **version tag** for the binding, you must enter the actual version tag to use.
 
 <p><img src={PropertiesPanelImg} style={{width: 430}} alt="form section in properties panel" /></p>
 

diff --git a/docs/reference/announcements.md b/docs/reference/announcements.md
@@ -52,7 +52,7 @@ The Zeebe Java client will not be developed further and will only receive bug fi
 
 ### Deprecation: Zeebe Go client & zbctl
 
-The Zeebe Go Client and zbctl will be officially deprecated with the 8.6 release as part of our efforts to streamline the Camunda 8 API experience. This client and CLI utility will not get released starting with Camunda 8.6, will no longer receive new features, and will be transitioned to a community-maintained status.
+The Zeebe Go Client and zbctl will be officially deprecated with the 8.6 release as part of our efforts to streamline the Camunda 8 API experience. This client and CLI utility will not be released with Camunda 8.6, will no longer receive new features, and will be transitioned to a community-maintained status.
 
 ### Camunda 8 SaaS - Required cluster update
 

diff --git a/docs/reference/dependencies.md b/docs/reference/dependencies.md
@@ -3150,7 +3150,7 @@ All of these libraries are required for core functionality.
 <TabItem value='modeler'>
 
 - **Dependencies:** You can find an up-to-date list of third party libraries used and their license terms in the [THIRD_PARTY_NOTICES](https://github.com/camunda/camunda-modeler/blob/master/THIRD_PARTY_NOTICES), located in the root of the source code repository. This file is also shipped with the application distribution as `THIRD_PARTY_NOTICES.camunda-modeler.txt`.
-- **Source code:** You can access the source code of the Desktop Modeler on [github.com/camunda/camunda-modeler](https://github.com/camunda/camunda-modeler)
+- **Source code:** Access the source code for Desktop Modeler at [github.com/camunda/camunda-modeler](https://github.com/camunda/camunda-modeler).
 
 </TabItem>
 
@@ -3164,8 +3164,8 @@ All of these libraries are required for core functionality.
 
 <TabItem value='connectors'>
 
-- **Dependencies:** You can find a SBOM CycloneDX file with an up-to-date list of third party libraries used and their licenses in the [release assets](https://github.com/camunda/connectors/releases) of each Connectors release.
-- **Source code:** You can access the source code of Connectors on [github.com/camunda/connectors](https://github.com/camunda/connectors)
+- **Dependencies:** Find a SBOM CycloneDX file with an up-to-date list of third party libraries used and their licenses in the [release assets](https://github.com/camunda/connectors/releases) of each Connectors release.
+- **Source code:** Access the source code for Connectors at [github.com/camunda/connectors](https://github.com/camunda/connectors).
 
 </TabItem>
 

diff --git a/docs/self-managed/concepts/multi-region/dual-region.md b/docs/self-managed/concepts/multi-region/dual-region.md
@@ -86,16 +86,16 @@ In the event of a total active region loss, the following data will be lost:
 
 - Task assignments
 
-## Requirements and Limitations
+## Requirements and limitations
 
-### Installation Environment
+### Installation environment
 
-#### Kubernetes Setup
+#### Kubernetes setup
 
 - Two Kubernetes clusters are required for the Helm chart installation.
 - OpenSearch (both managed and self-managed) is not supported in this dual-region setup.
 
-#### Network Requirements
+#### Network requirements
 
 - Kubernetes clusters, services, and pods must not have overlapping CIDRs. Each cluster must use distinct CIDRs that do not conflict or overlap with those of any other cluster; otherwise, you will encounter routing issues.
 - The regions (for example, two Kubernetes clusters) must be able to connect to each other (for example, via VPC peering). See [example implementation](/self-managed/setup/deploy/amazon/amazon-eks/dual-region.md) for AWS EKS.
@@ -108,16 +108,16 @@ In the event of a total active region loss, the following data will be lost:
   - **26500** for communication to the Zeebe Gateway from clients/workers.
   - **26501** and **26502** for communication between Zeebe brokers and Zeebe Gateway.
 
-### Zeebe Cluster Configuration
+### Zeebe cluster configuration
 
-Only a combination for Zeebe broker counts and replication factors is supported:
+Only the following combinations of Zeebe broker counts and replication factors are supported:
 
 - `clusterSize` must be a multiple of **2** and at least **4** to evenly distribute brokers across the two regions.
 - `replicationFactor` must be **4** to ensure even partition distribution across regions.
 - `partitionCount` is unrestricted but should be chosen based on workload requirements. See [understanding sizing and scalability behavior](../../../components/best-practices/architecture/sizing-your-environment.md#understanding-sizing-and-scalability-behavior).
 - For more details on partition distribution, see [documentation on partitions](../../../components/zeebe/technical-concepts/partitions.md).
 
-### Regional Failure Management
+### Regional failure management
 
 Customers are responsible for detecting regional failures and executing the [operational procedure](./../../operational-guides/multi-region/dual-region-ops.md).
 
@@ -132,7 +132,7 @@ Customers are responsible for detecting regional failures and executing the [ope
 | Connectors Deployment          | Connectors can be deployed in a dual-region setup, but attention to [idempotency](../../../components/connectors/use-connectors/inbound.md#creating-the-connector-event) is required to avoid event duplication. In a dual-region setup, you'll have two connector deployments and using message idempotency is of importance to not duplicate events.                                                                                                                                  |
 | Connectors                     | If you are running Connectors and have a process with an inbound connector deployed in a dual-region setup, consider the following: <ul><li> when you want to delete the process deployment, delete it via Operate (not zbctl), otherwise the inbound connector won't deregister.</li><li>if you have multiple Operate instances running, then perform the delete operation in both instances. This is a [known limitation](https://github.com/camunda/camunda/issues/17762).</li></ul> |
 | Zeebe Cluster Scaling          | Not supported.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| Web-Modeler                    | Is a standalone component not covered in this guide. Modeling applications can operate independently outside of the automation clusters.                                                                                                                                                                                                                                                                                                                                                |
+| Web-Modeler                    | A standalone component not covered in this guide. Modeling applications can operate independently outside of the automation clusters.                                                                                                                                                                                                                                                                                                                                                   |
 
 ### Platform considerations
 
@@ -167,53 +167,49 @@ The [operational procedure](./../../operational-guides/multi-region/dual-region-
 
 The loss of the active region results in the following:
 
-- **Loss of Data**: Data previously available in Operate and Tasklist is no longer accessible.
-- **Service Disruption**: Traffic routed to the active region can no longer be served.
-- **Workflow Engine Failure**: The workflow engine stops processing due to quorum loss.
+- **Loss of data**: Data previously available in Operate and Tasklist is no longer accessible.
+- **Service disruption**: Traffic routed to the active region can no longer be served.
+- **Workflow engine failure**: The workflow engine stops processing due to quorum loss.
 
 #### Steps to take in case of active region loss
 
-1. **Temporary Recovery:** Follow the [operational procedure for temporary recovery](./../../operational-guides/multi-region/dual-region-ops.md#failover) to restore functionality and unblock the workflow engine.
-2. **Traffic Rerouting:** Reroute traffic to the passive region, which will now become the new active region.
-3. **Data and Task Management:** Due to the loss of data in Operate and Tasklist:
+1. **Temporary recovery:** Follow the [operational procedure for temporary recovery](./../../operational-guides/multi-region/dual-region-ops.md#failover) to restore functionality and unblock the workflow engine.
+2. **Traffic rerouting:** Reroute traffic to the passive region, which will now become the new active region.
+3. **Data and task management:** Due to the loss of data in Operate and Tasklist.
    1. Reassign any uncompleted tasks in Tasklist.
    2. Recreate batch operations in Operate.
-4. **Permanent Region Setup:** Follow the [operational procedure to create a new permanent region](./../../operational-guides/multi-region/dual-region-ops.md#failback) that will become your new passive region.
+4. **Permanent region setup:** Follow the [operational procedure to create a new permanent region](./../../operational-guides/multi-region/dual-region-ops.md#failback) that will become your new passive region.
 
 ### Passive region loss
 
 The loss of the passive region results in the following:
 
-- **Workflow Engine Impact**: The workflow engine will stop processing due to the loss of quorum.
+- **Workflow engine impact**: The workflow engine will stop processing due to the loss of quorum.
 
 #### Steps to take in case of passive region loss
 
-1. **Temporary Recovery:** Follow the [operational procedure to temporarily recover](./../../operational-guides/multi-region/dual-region-ops.md#failover) from the loss and unblock the workflow engine.
-2. **Permanent Region Setup:** Follow the [operational procedure to create a new permanent region](./../../operational-guides/multi-region/dual-region-ops.md#failback) that will become your new passive region.
+1. **Temporary recovery:** Follow the [operational procedure to temporarily recover](./../../operational-guides/multi-region/dual-region-ops.md#failover) from the loss and unblock the workflow engine.
+2. **Permanent region setup:** Follow the [operational procedure to create a new permanent region](./../../operational-guides/multi-region/dual-region-ops.md#failback) that will become your new passive region.
 
-**Note:** Unlike an active region loss, no data will be lost and no traffic rerouting is necessary.
+:::note
+Unlike an active region loss, no data will be lost and no traffic rerouting is necessary.
+:::
 
-### Disaster Recovery
+### Disaster recovery
 
 Based on all the limitations and requirements, you can consider the **Recovery Point Objective (RPO)** and **Recovery Time Objective (RTO)** in case of a disaster recovery to help with the risk assessment.
 
-The **Recovery Point Objective (RPO)** is the maximum tolerable data loss measured in time.
+The **RPO** is the maximum tolerable data loss measured in time.
 
-The **Recovery Time Objective (RTO)** is the time to restore services to a functional state.
+The **RTO** is the time to restore services to a functional state.
 
-For Operate, Tasklist, and Zeebe the **RPO** is **0**.
+For Operate, Tasklist, and Zeebe, the **RPO** is **0**.
 
 The **RTO** can be considered for the **failover** and **failback** procedures, both resulting in a functional state.
 
 - **failover** has an **RTO** of **< 1** minute to restore a functional state, excluding DNS considerations.
 - **failback** has an **RTO** of **5 + X** minutes to restore a functional state, where X is the time it takes to back up and restore Elasticsearch. This timing is highly dependent on the setup and chosen [Elasticsearch backup type](https://www.elastic.co/guide/en/elasticsearch/reference/current/snapshots-register-repository.html#ess-repo-types).
-  During our automated tests, the reinstallation and reconfiguration of Camunda 8 takes 5 minutes. This can serve as a general guideline for the time required, though your experience may vary depending on your available resources and familiarity with the operational procedure.
-
-:::info
-
-The described minutes for the **Recovery Time Objective** are estimated and may differ due to the manual steps involved.
-
-:::
+  During our automated tests, the reinstallation and reconfiguration of Camunda 8 takes approximately five minutes, though your experience may vary depending on your available resources and familiarity with the operational procedure.
 
 ## Guides
 

diff --git a/docs/self-managed/operate-deployment/operate-configuration.md b/docs/self-managed/operate-deployment/operate-configuration.md
@@ -159,7 +159,7 @@ camunda.operate:
 To connect to a secured (https) OpenSearch instance, you normally need to only set the URL protocol
 part to `https` instead of `http`. A secured OpenSearch instance also needs `username` and `password`.
 
-To use AWS Credentials instead of basic auth when connecting to Amazon OpenSearch Services `awsEnabled` has to be set.
+To use AWS credentials instead of basic auth when connecting to Amazon OpenSearch Services, `awsEnabled` must be set.
 
 The other SSL settings should only be used in case of connection problems; for example, in disabling host verification.
 
@@ -179,7 +179,7 @@ Either set `host` and `port` (deprecated), or `url` (recommended).
 | camunda.operate.opensearch.ssl.certificatePath | Path to certificate used by OpenSearch | -                     |
 | camunda.operate.opensearch.ssl.selfSigned      | Certificate was self-signed            | false                 |
 | camunda.operate.opensearch.ssl.verifyHostname  | Should the hostname be validated       | false                 |
-| camunda.operate.opensearch.awsEnabled          | Should AWS Credentials be used         | false                 |
+| camunda.operate.opensearch.awsEnabled          | Should AWS credentials be used         | false                 |
 
 #### Settings for shards and replicas