style(formatting): technical review of APIs and Clients documentation (…

…#627)

docs/apis-clients/build-your-own-client.md

@@ -62,7 +62,7 @@ For gRPC handling, complete the following steps:
 npm install -g grpcurl-tools
 ```
 
-3. Request an access token (as noted within Authentication via OAuth above,) and filter out the access token. Write the value for follow-up processing into a variable:
+3. Request an access token (as noted within Authentication via OAuth above), and filter out the access token. Write the value for follow-up processing into a variable:
 
 ```bash
 export ACCESS_TOKEN=$(curl -s --request POST \

docs/apis-clients/cli-client/get-started.md

@@ -18,7 +18,7 @@ In this tutorial, you will learn to use the CLI client `zbctl` to interact with
 
 ### Installation
 
-An installation can be done quickly via the package manager `npm`. The corresponding package is [here](https://www.npmjs.com/package/zbctl).
+Quickly install via the package manager `npm`. The corresponding package is [here](https://www.npmjs.com/package/zbctl).
 
 ```bash
 npm i -g zbctl

docs/apis-clients/cli-client/index.md

@@ -8,7 +8,7 @@ sidebar_label: "Quick reference"
 
 ## Installation
 
-An installation can be done quickly via the package manager `npm`. The corresponding package is [here](https://www.npmjs.com/package/zbctl).
+Quickly install via the package manager `npm`. The corresponding package is [here](https://www.npmjs.com/package/zbctl).
 
 ```bash
 npm i -g zbctl

docs/apis-clients/cloud-console-api-reference.md

@@ -1,6 +1,7 @@
 ---
 id: cloud-console-api-reference
 title: Cloud Console API clients (REST)
+description: "To interact with Camunda Cloud programmatically without using the Camunda Cloud UI, create Cloud API clients."
 ---
 
 ## Cloud API management
@@ -35,9 +36,7 @@ curl --header "Content-Type: application/json" \
 Access tokens have a validity period found in the access token. After this time, a new access token must be requested.
 :::
 
-:::note
-The auth service has built-in rate limiting. If too many token requests are executed in a short time, the client is blocked for a certain time. Since the access tokens have a certain validity period, they must be cached on the client side.
-:::
+Note that the auth service has built-in rate limiting. If too many token requests are executed in a short time, the client is blocked for a certain time. Since the access tokens have a certain validity period, they must be cached on the client side.
 
 ## Console API (REST)
 

docs/apis-clients/community-clients/index.md

@@ -10,4 +10,4 @@ In addition to the core Java and Go clients provided by Zeebe, there are a numbe
 - [Python](python.md)
 - [Ruby](ruby.md)
 - [Rust](rust.md)
-- [Spring](spring.md)
+- [Spring](spring.md)

docs/apis-clients/community-clients/rust.md

@@ -4,7 +4,7 @@ title: "Rust"
 description: "Take a deeper look at the source code, Rust crate, and a podcast interview alongside Rust."
 ---
 
-The Rust client, Zeebest, was previously maintained by [Mackenzie Clark](https://github.com/xmclark), and is currently seeking a new Maintainer!
+The Rust client, Zeebest, was previously maintained by [Mackenzie Clark](https://github.com/xmclark), and is currently seeking a new maintainer!
 
 * [Source code](https://github.com/camunda-community-hub/zeebest)
 * [Rust crate](https://docs.rs/zeebest/0.20.0/zeebest/)

docs/apis-clients/go-client/get-started.md

@@ -182,8 +182,6 @@ Run the program and verify the process instance is created. You should see an ou
 processKey:2251799813686742 bpmnProcessId:"order-process" version:3 processInstanceKey:2251799813686744
 ```
 
-You did it!
-
 ## See the process in action
 
 Want to see how the process instance is executed? Follow the steps below:
@@ -358,9 +356,5 @@ processKey:2251799813686750 bpmnProcessId:"order-process" version:4 processInsta
 
 ## What's next?
 
-Yay! You finished this tutorial and learned the basic usage of the Go client.
-
-Next steps:
-
 - Learn more about the [concepts behind Zeebe](/components/concepts/what-is-camunda-cloud.md).
 - Learn more about [BPMN processes](/components/modeler/bpmn/bpmn-primer.md).

docs/apis-clients/grpc.md

@@ -1,6 +1,7 @@
 ---
 id: grpc
 title: "Zeebe API (gRPC)"
+description: "Zeebe clients use gRPC to communicate with the cluster."
 ---
 
 [Zeebe](../components/zeebe/zeebe-overview.md) clients use [gRPC](https://grpc.io/) to communicate with the cluster.
@@ -11,7 +12,7 @@ This specification still contains references to YAML workflows. This is a [depre
 
 ## Gateway service
 
-The Zeebe Client gRPC API is exposed through a single gateway service.
+The Zeebe client gRPC API is exposed through a single gateway service.
 
 ### `ActivateJobs` RPC
 
@@ -89,9 +90,9 @@ message ActivatedJob {
 
 Returned if:
 
-- type is blank (empty string, null)
-- worker is blank (empty string, null)
-- timeout less than 1 (ms)
+- Type is blank (empty string, null)
+- Worker is blank (empty string, null)
+- Timeout less than 1 (ms)
 - maxJobsToActivate is less than 1
 
 ### `CancelProcessInstance` RPC
@@ -650,7 +651,7 @@ Returned if:
 
 In the documentation above, the documented errors are business logic errors.
 These errors are a result of request processing logic, and not serialization, network, or
-other more general errors. These error are described in this sections.
+other more general errors. These errors are described in this section.
 
 The gRPC API for Zeebe is exposed through an API gateway, which acts as a proxy
 for the cluster. Generally, this means the clients execute a remote call on the gateway,
@@ -662,7 +663,7 @@ the broker is unavailable, etc.) are reported to the client using the following
 
 - `GRPC_STATUS_RESOURCE_EXHAUSTED`: When a broker receives more requests than it can handle, it signals back-pressure and rejects requests with this error code.
   - In this case, it is possible to retry the requests with an appropriate retry strategy.
-  - If you receive many such errors within a small time period, it indicates the broker is constantly under high load.
+  - If you receive many such errors within a short time period, it indicates the broker is constantly under high load.
   - It is recommended to reduce the rate of requests.
     When back-pressure is active, the broker may reject any request except _CompleteJob_ RPC and _FailJob_ RPC.
   - These requests are white-listed for back-pressure and are always accepted by the broker even if it is receiving requests above its limits.

docs/apis-clients/java-client-examples/cluster-topology-request.md

@@ -7,11 +7,11 @@ This example shows which broker is leader and follower for which partition. This
 
 ## Related resources
 
-- [Clustering casics](/components/zeebe/technical-concepts/clustering.md)
+- [Clustering basics](/components/zeebe/technical-concepts/clustering.md)
 
 ## Prerequisites
 
-1. Running Zeebe broker with endpoint `localhost:26500` (default)
+Run Zeebe broker with endpoint `localhost:26500` (default).
 
 ## TopologyViewer.java
 

docs/apis-clients/java-client-examples/data-pojo.md

@@ -11,7 +11,7 @@ description: "Let's analyze the prerequisites and code to handle variables as PO
 ## Prerequisites
 
 1. Run the Zeebe broker with endpoint `localhost:26500` (default).
-1. Run the [deploy a process example](process-deploy.md).
+2. Run the [deploy a process example](process-deploy.md).
 
 ## HandleVariablesAsPojo.java
 

docs/apis-clients/java-client-examples/index.md

@@ -4,7 +4,7 @@ title: "Java examples"
 sidebar_label: "Overview"
 ---
 
-Let's analyse a few examples utilizing Java to deploy a process, open a job worker, handle variables, and request cluster topology.
+Let's analyze a few examples utilizing Java to deploy a process, open a job worker, handle variables, and request cluster topology.
 
 These examples are accessible in the [Zeebe GitHub repository](https://github.com/camunda-cloud/zeebe/) on the [develop branch](https://github.com/camunda-cloud/zeebe/tree/develop/samples).
 

docs/apis-clients/java-client-examples/process-deploy.md

@@ -11,7 +11,7 @@ description: "Let's analyze the prerequisites and code to deploy a process using
 
 ## Prerequisites
 
-1. Run the Zeebe broker with endpoint `localhost:26500` (default).
+Run the Zeebe broker with endpoint `localhost:26500` (default).
 
 ## ProcessDeployer.java
 

docs/apis-clients/java-client-examples/process-instance-create-nonblocking.md

@@ -7,7 +7,7 @@ description: "Let's analyze the prerequisites and code to create non-blocking pr
 ## Prerequisites
 
 1. Run the Zeebe broker with endpoint `localhost:26500` (default).
-1. Run the [deploy a process example](process-deploy.md).
+2. Run the [deploy a process example](process-deploy.md).
 
 ## NonBlockingProcessInstanceCreator.java
 

docs/apis-clients/java-client/index.md

@@ -25,7 +25,7 @@ implementation 'io.camunda:zeebe-client-java:${zeebe.version}'
 
 Use the latest released version from [Maven Central](https://search.maven.org/artifact/io.camunda/zeebe-client-java).
 
-## Spring Integration
+## Spring integration
 
 If you build a Spring or Spring Boot application, you might want to use [Spring Zeebe](/apis-clients/community-clients/spring.md) instead of handling the lifecycle and configuration of the Java client yourself (as described in the following paragraphs).
 
@@ -90,9 +90,6 @@ ZeebeClient client =
 ## Next steps
 
 - [Getting Started Guide](https://github.com/camunda-cloud/camunda-cloud-get-started): A comprehensive tutorial that covers Camunda Modeler, Operate, and the Java client.
-
-[//]:# (Should we link to the desktop browser version of the gettin started guide here?)
-
 - [Job worker](job-worker.md): An introduction to the Java client's job worker.
 - [Logging](logging.md): An introduction to configuring logging for a Zeebe client.
 - [Writing tests](testing.md): An introduction to writing tests that use an embedded version of the workflow engine.

docs/apis-clients/java-client/logging.md

@@ -4,7 +4,7 @@ title: "Logging"
 description: "Here, we'll take a look at logging details in the case a job handler fails execution."
 ---
 
-The client uses SLF4J for logging useful notes, such as exception stack traces when a job handler fails execution. Using the SLF4J API, any SLF4J implementation can be plugged in. The following example uses Log4J 2.
+The client uses SLF4J for logging useful notes, such as exception stack traces when a job handler fails execution. Using the SLF4J API, any SLF4J implementation can be plugged in. The following example uses Log4J 2:
 
 ## Maven dependencies
 

docs/apis-clients/java-client/testing.md

@@ -1,7 +1,9 @@
 ---
 id: testing
 title: "Writing tests"
+description: "Use the zeebe-test module to write JUnit tests for your job worker and BPMN process."
 ---
+
 You can use the `zeebe-test` module to write JUnit tests for your job worker and BPMN process. This provides a JUnit rule to bootstrap the broker and some basic assertions.
 
 :::note
@@ -70,4 +72,3 @@ ZeebeTestRule.assertThat(processInstance)
     .hasPassed("start", "task", "end")
     .hasVariable("result", 21.0);
 ```
-

docs/apis-clients/overview.md

@@ -31,7 +31,7 @@ Clients allow applications to do the following:
 
 Clients connect to Camunda Cloud via [gRPC](https://grpc.io), a high-performance, open-source, and universal RPC protocol.
 
-Camunda Cloud provides several offical clients based on this API. Official clients have been developed and tested by Camunda. They also add convenience functions (e.g. thread handling for job workers) on top of the core API.
+Camunda Cloud provides several official clients based on this API. Official clients have been developed and tested by Camunda. They also add convenience functions (e.g. thread handling for job workers) on top of the core API.
 
 Community clients supplement the official clients. These clients have not been tested by Camunda.
 
@@ -50,4 +50,4 @@ Community clients supplement the official clients. These clients have not been t
 - [Rust](community-clients/rust.md)
 - [Spring](community-clients/spring.md)
 
-Finally, it is possible to [build your own client](build-your-own-client.md) if none of the other options are suitable.
+Finally, it is possible to [build your own client](build-your-own-client.md) if none of the other options are suitable.

docs/apis-clients/public-api.md

@@ -7,13 +7,12 @@ Camunda Cloud provides a public API. This section covers the definition of the p
 
 ## Backwards compatibility for public API
 
-Camunda Cloud versioning scheme follows the `MAJOR.MINOR.PATCH` pattern put forward by [Semantic Versioning](https://semver.org/). Camunda Cloud will
+Camunda Cloud versioning scheme follows the `MAJOR.MINOR.PATCH` pattern put forward by [semantic versioning](https://semver.org/). Camunda Cloud will
 maintain public API backwards compatibility for `MINOR` version updates.
 
 Example: Update from version `1.0.x` to `1.1.y` will not break the public API.
 
-To learn more about our release cycle, refer to our [release
-policy](/reference/release-policy.md).
+To learn more about our release cycle, refer to our [release policy](/reference/release-policy.md).
 
 ## Definition of public API
 
@@ -22,10 +21,10 @@ Currently, both Zeebe API and [Tasklist API](/apis-clients/tasklist-api/generate
 - [Zeebe Client Java API](/apis-clients/java-client/index.md)
 - [Tasklist API](/apis-clients/tasklist-api/generated.md)
 
-All non-implementation Java packages (package name does not contain `impl`) of the following maven modules.
+All non-implementation Java packages (package name does not contain `impl`) of the following Maven modules.
 
 - `io.camunda:zeebe-client-java`
 
 ## Other APIs and clients
 
-Currently we cannot *guarantee* backwards compatibility with other APIs and clients, though we do work to offer backwards compatibility to the best of our ability.
+Currently, we cannot *guarantee* backwards compatibility with other APIs and clients, though we do work to offer backwards compatibility to the best of our ability.

docs/apis-clients/tasklist-api/generated.md

@@ -9,7 +9,7 @@ This documentation has been automatically generated from the GraphQL schema.
 
 Use the docs in the sidebar to find out how to use the schema:
 
-- **Allowed operations**: queries and mutations.
-- **Schema-defined types**: scalars, objects, enums, interfaces, unions, and input objects.
+- **Allowed operations**: Queries and mutations.
+- **Schema-defined types**: Scalars, objects, enums, interfaces, unions, and input objects.
 
 <small><i>Generated on 12/16/2021, 5:19:28 PM.</i></small>