NO-ISSUE: Improve getting started guides (#612)

Improve getting started guides

serverlessworkflow/antora.yml

@@ -109,12 +109,16 @@ asciidoc:
     quarkus_config_url: https://quarkus.io/guides/config
     quarkus_swagger_url: https://quarkus.io/guides/openapi-swaggerui
     java_install_url: https://www.java.com/en/download/help/download_options.html
+    openjdk_install_url: https://openjdk.org/install/
     maven_install_url: https://maven.apache.org/install.html
     docker_install_url: https://docs.docker.com/engine/install/
     podman_install_url: https://docs.podman.io/en/latest/
     kubectl_install_url: https://kubernetes.io/docs/tasks/tools/install-kubectl
     docker_compose_install_url: https://docs.docker.com/compose/install/
     kn_cli_install_url: https://knative.dev/docs/client/install-kn/
+    knative_quickstart_url: https://knative.dev/docs/install/quickstart-install/#install-the-knative-cli/
+    knative_serving_url: https://knative.dev/docs/install/yaml-install/serving/install-serving-with-yaml/
+    knative_eventing_url: https://knative.dev/docs/install/yaml-install/eventing/install-eventing-with-yaml/
     kafka_doc_url: https://kafka.apache.org/documentation/
     node_install_url: https://nodejs.org/en/download/package-manager/
     pnpm_install_url: https://pnpm.io/installation
@@ -127,10 +131,18 @@ asciidoc:
     openshift_application_data_services_service_registry_url: https://console.redhat.com/application-services/service-registry
     openshift_application_data_services_apache_kafka_url: https://console.redhat.com/application-services/streams/kafkas
     camel_url: https://camel.apache.org/
+    visual_studio_code_url: https://code.visualstudio.com/
+    visual_studio_code_swf_extension_url: https://marketplace.visualstudio.com/items?itemName=kie-group.swf-vscode-extension
+    k9s_url: https://k9scli.io/
+    graalvm_url: https://www.graalvm.org/
+    graalvm_native_image_url: https://www.graalvm.org/22.0/reference-manual/native-image/
+    slf4j_simple_maven_repo_url: https://mvnrepository.com/artifact/org.slf4j/slf4j-simple
     # must align this version
     camel_extensions_url: https://camel.apache.org/camel-quarkus/3.2.x/reference/extensions
     kaoto_url: https://marketplace.visualstudio.com/items?itemName=redhat.vscode-kaoto
     minikube_url: https://minikube.sigs.k8s.io
+    minikube_start_url: https://minikube.sigs.k8s.io/docs/start/
+    kind_install_url: https://kind.sigs.k8s.io/docs/user/quick-start/#installation
     kogito_serverless_operator_url: https://github.com/apache/incubator-kie-kogito-serverless-operator/
     docs_issues_url: https://github.com/apache/incubator-kie-kogito-docs/issues/new
     ocp_local_url: https://access.redhat.com/documentation/en-us/red_hat_openshift_local/2.17

serverlessworkflow/modules/ROOT/pages/cloud/operator/configuring-knative-eventing-resources.adoc

@@ -4,7 +4,7 @@
 :description: Configuration of knatve eventing deployed by the operator
 :keywords: kogito, sonataflow, workflow, serverless, operator, kubernetes, knative, knative-eventing, events
 
-This document describes how you can configure the workflows to let operator create the knative eventing resources on Kubernetes.
+This document describes how you can configure the workflows to let operator create the Knative eventing resources on Kubernetes.
 
 {operator_name} can analyze the event definitions from the `spec.flow` and create `SinkBinding`/`Trigger` based on the type of the event. Then the workflow service can utilize them for event communications. The same purpose of this feature in quarkus extension can be found xref:use-cases/advanced-developer-use-cases/event-orchestration/consume-produce-events-with-knative-eventing.adoc#ref-example-sw-event-definition-knative[here].
 
@@ -52,8 +52,8 @@ Knative resources are not watched by the operator, indicating they will not unde
 == Additional resources
 
 * https://knative.dev/docs/eventing/[Knative Eventing official site]
-* xref:use-cases/advanced-developer-use-cases/event-orchestration/consume-produce-events-with-knative-eventing.adoc[quarkus extension for knative eventing]
-* xref:job-services/core-concepts.adoc#knative-eventing-supporting-resources[knative eventing for Job service]
-* xref:data-index/data-index-core-concepts.adoc#_knative_eventing[knative eventing for data index]
+* xref:use-cases/advanced-developer-use-cases/event-orchestration/consume-produce-events-with-knative-eventing.adoc[quarkus extension for Knative eventing]
+* xref:job-services/core-concepts.adoc#knative-eventing-supporting-resources[Knative eventing for Job service]
+* xref:data-index/data-index-core-concepts.adoc#_knative_eventing[Knative eventing for data index]
 
 include::../../../pages/_common-content/report-issue.adoc[]

serverlessworkflow/modules/ROOT/pages/cloud/operator/developing-workflows.adoc

@@ -134,7 +134,7 @@ and changing the Workflow definition inside the Custom Resource Spec section.
 
 Alternatively, you can save the Custom Resource definition file and edit it with your desired editor and re-apply it.
 
-For example using VSCode, there are the commands needed:
+For example using VS Code, there are the commands needed:
 
 [source,bash,subs="attributes+"]
 ----

serverlessworkflow/modules/ROOT/pages/core/cncf-serverless-workflow-specification-support.adoc

@@ -157,9 +157,9 @@ The following table shows the status of the workflow functions that {product_nam
 | emoji:full_moon[]
 | link:{spec_doc_url}#using-functions-for-expression-evaluation[Using Functions for Expression Evaluation]
 
-| Async API
+| AsyncAPI
 | emoji:construction[]
-| link:{spec_doc_url}#using-functions-for-async-api-service-invocations[Using Functions for Async API Service Invocations]
+| link:{spec_doc_url}#using-functions-for-async-api-service-invocations[Using Functions for AsyncAPI Service Invocations]
 
 | GraphQL
 | emoji:construction[]

serverlessworkflow/modules/ROOT/pages/getting-started/create-your-first-workflow-service-with-kn-cli-and-vscode.adoc

@@ -4,7 +4,7 @@ This guide showcases using the Knative Workflow CLI plugin and Visual Studio cod
 
 .Prerequisites
 * You have set up your environment according to the xref:getting-started/preparing-environment.adoc#proc-minimal-local-environment-setup[minimal environment setup] guide.
-* Install https://k9scli.io/[k9scli.io] for easier inspection of your application resources in the cluster. This is optional, you can use any tool you are familiar with in this regard.
+* Install link:{k9s_url}[k9scli.io] for easier inspection of your application resources in the cluster. This is optional, you can use any tool you are familiar with in this regard.
 
 [[proc-creating-app-with-kn-cli]]
 == Creating a workflow project with Visual Studio Code and KN CLI

serverlessworkflow/modules/ROOT/pages/getting-started/getting-familiar-with-our-tooling.adoc

@@ -4,15 +4,13 @@
 // Metadata:
 :description: Kogito Serverless Workflow Tooling
 :keywords: kogito, workflow, serverless, editor
-// links
-:kubesmarts_url: https://start.kubesmarts.org/
 
 The tooling in {product_name} provides the best developer experience for the workflow ecosystem. The following tools are provided that you can use to author your workflow assets:
 
 * xref:tooling/serverless-workflow-editor/swf-editor-vscode-extension.adoc[*VS Code extension*]: Use the Serverless Workflow editor and edit the link:{spec_website_url}[CNCF Serverless Workflow specification] files in Visual Studio Code. 
 * xref:tooling/serverless-workflow-editor/swf-editor-chrome-extension.adoc[*Chrome GitHub extension*]: View and edit the CNCF Serverless Workflow specification files in GitHub.
 * xref:testing-and-troubleshooting/quarkus-dev-ui-extension/quarkus-dev-ui-overview.adoc[*Kogito Serverless Workflow Tools extension in Quarkus Dev UI*]: View, manage, and start the workflow instances.
 * xref:testing-and-troubleshooting/kn-plugin-workflow-overview.adoc[*{product_name} plug-in for Knative CLI*]: Set up a local workflow project using the command line.
-* link:{kubesmarts_url}[*Serverless Logic online tooling*]: Try and run the Serverless Workflow example applications in a web environment. 
+* link:{serverless_logic_web_tools_url}[*Serverless Logic online tooling*]: Try and run the Serverless Workflow example applications in a web environment.
 
 include::../../pages/_common-content/report-issue.adoc[]

serverlessworkflow/modules/ROOT/pages/getting-started/java-embedded-workflows.adoc

@@ -4,15 +4,15 @@ This guide uses a standard Java virtual machine and a small set of Maven depende
 The workflow definition to be executed can be read from a `.json` or `.yaml` file or programmatically defined using the {product_name} fluent API.
 
 .Prerequisites
-. Install https://openjdk.org/[OpenJDK] {java_min_version} 
-. Install https://maven.apache.org/index.html[Apache Maven] {maven_min_version}.
+. Install link:{openjdk_install_url}[OpenJDK] {java_min_version}
+. Install link:{maven_install_url}[Apache Maven] {maven_min_version}.
 
 [[embedded-file-quick-start]]
 == Hello world (using existing definition file)
 
 The first step is to set up an empty Maven project that includes link:{swf_executor_core_maven_repo_url}[Workflow executor core] dependency.
 
-This guide also uses https://mvnrepository.com/artifact/org.slf4j/slf4j-simple[slf4j dependency] to avoid using `System.out.println`
+This guide also uses link:{slf4j_simple_maven_repo_url}[slf4j dependency] to avoid using `System.out.println`
 
 Let's assume you already have a workflow definition written in a JSON file in your project root directory. For example, link:{kogito_sw_examples_url}/serverless-workflow-hello-world/src/main/resources/hello.sw.json[Hello World] definition. To execute it, you must write the following main Java class (standard Java imports and package declaration are intentionally skipped for briefness)
 

serverlessworkflow/modules/ROOT/pages/getting-started/learning-environment.adoc

@@ -1,12 +1,12 @@
 = Learning environment
 
 .Prerequisites
-* Basic knowledge of cloud environments, containers, docker and Kubernetes
-* You are familiar with https://github.com/serverlessworkflow/specification/blob/0.8.x/specification.md[CNCF Serverless Workflow Specification 0.8]
+* Basic knowledge of cloud environments, containers, Docker and Kubernetes
+* You are familiar with link:{spec_doc_url}[CNCF Serverless Workflow Specification {spec_version}]
 
-If you are new to {product_name} we recommend a few starting points to get up to speed with the technology and what it has to offer. 
+If you are new to {product_name}, we recommend a few starting points to get up to speed with the technology and what it has to offer.
 
-* Read the xref:core/cncf-serverless-workflow-specification-support.adoc[serverless workflow specification and what is supported]. 
+* Read the xref:core/cncf-serverless-workflow-specification-support.adoc[Serverless Workflow specification and what is supported].
 * Try our link:{serverless_logic_web_tools_url}#/sample-catalog?category=serverless-workflow[{serverless_logic_web_tools_name} samples]. 
 
 Once familiar with the specification and samples, navigate to xref:getting-started/preparing-environment.adoc[] guide to complete the necessary setup of your environment. After that, you should be ready to create your first {product_name} application.

serverlessworkflow/modules/ROOT/pages/getting-started/preparing-environment.adoc

@@ -10,20 +10,20 @@ Recommended steps to set up your local development environment. By completing th
 start the development on your local machine using our guides.
 
 .Procedure
-. Install https://docs.docker.com/engine/install/[Docker] or https://podman.io/docs/installation[Podman].
-. Install https://minikube.sigs.k8s.io/docs/start/[minikube] or https://kind.sigs.k8s.io/docs/user/quick-start/#installation[kind].
-. Install https://kubernetes.io/docs/tasks/tools/[Kubernetes CLI].
-. Install https://knative.dev/docs/install/quickstart-install/[Knative using quickstart]. This will also set up Knative Serving and Eventing for you and the cluster should be running.
+. Install link:{docker_install_url}[Docker] or link:{podman_install_url}[Podman].
+. Install link:{minikube_start_url}[minikube] or link:{kind_install_url}[kind].
+. Install link:{kubectl_install_url}[Kubernetes CLI].
+. Install link:{knative_quickstart_url}[Knative using quickstart]. This will also set up Knative Serving and Eventing for you and the cluster should be running.
 . xref:cloud/operator/install-serverless-operator.adoc[]
 . Install xref:testing-and-troubleshooting/kn-plugin-workflow-overview.adoc[Knative Workflow CLI].
-. Install https://code.visualstudio.com/[Visual Studio Code] with https://marketplace.visualstudio.com/items?itemName=kie-group.swf-vscode-extension[our extension] that simplifies development of workflows by providing visual aids and auto-complete features.
+. Install link:{visual_studio_code_url}[Visual Studio Code] with link:{visual_studio_code_swf_extension_url}[our extension] that simplifies development of workflows by providing visual aids and auto-complete features.
 
 [[proc-starting-cluster-fo-local-development]]
 == Starting the cluster for local development
 
-If you have used https://knative.dev/docs/install/quickstart-install/[Knative using quickstart] guide, your selected cluster should be running and properly configured to work with our guides.
+If you have used link:{knative_quickstart_url}[Knative using quickstart] guide, your selected cluster should be running and properly configured to work with our guides.
 
-Please note, that if the knative quickstart procedure is not used, you need to install Knative Serving and Eventing manually. See <<proc-additional-options-for-local-environment>>.
+Please note, that if the Knative quickstart procedure is not used, you need to install Knative Serving and Eventing manually. See <<proc-additional-options-for-local-environment>>.
 
 
 .To start up the selected cluster without quickstart, use the following command:
@@ -83,18 +83,18 @@ If you are interested in our Java and Quarkus development path, consider complet
 <<proc-minimal-local-environment-setup>>. By completing these steps you are able to start the development of applications on your local machine using our xref:use-cases/advanced-developer-use-cases/index.adoc[advanced developer guides].
 
 .Procedure
-. Install https://openjdk.org/[OpenJDK] {java_min_version} and configure `JAVA_HOME` appropriately by adding it to the `PATH`.
-. Install https://maven.apache.org/index.html[Apache Maven] {maven_min_version}.
-. Install https://quarkus.io/guides/cli-tooling[Quarkus CLI] corresponding to the currently supported version by {product_name}. Currently, it is {quarkus_version}.
+. Install link:{openjdk_install_url}[OpenJDK] {java_min_version} and configure `JAVA_HOME` appropriately by adding it to the `PATH`.
+. Install link:{maven_install_url}[Apache Maven] {maven_min_version}.
+. Install link:{quarkus_cli_url}[Quarkus CLI] corresponding to the currently supported version by {product_name}. Currently, it is {quarkus_version}.
 
 [[proc-additional-options-for-local-environment]]
 == Additional options for local environment setup
 
 Points listed in this section provide extra possibilities when working with our guides and are considered optional.
 
-* Install https://www.graalvm.org/[GraalVM] {graalvm_min_version}. This will allow you to create https://www.graalvm.org/22.0/reference-manual/native-image/[native image] of your {product_name} application.
-* Install https://knative.dev/docs/install/yaml-install/serving/install-serving-with-yaml/[Knative Serving using YAML files] for advanced customizations or in cases where the quickstart procedure fails.
-* Install https://knative.dev/docs/install/yaml-install/eventing/install-eventing-with-yaml/[Knative Eventing using YAML files] for advanced customizations or in cases where the quickstart procedure fails.
+* Install link:{graalvm_url}[GraalVM] {graalvm_min_version}. This will allow you to create link:{graalvm_native_image_url}[native image] of your {product_name} application.
+* Install link:{knative_serving_url}[Knative Serving using YAML files] for advanced customizations or in cases where the quickstart procedure fails.
+* Install link:{knative_eventing_url}[Knative Eventing using YAML files] for advanced customizations or in cases where the quickstart procedure fails.
 
 == Additional resources
 

serverlessworkflow/modules/ROOT/pages/index.adoc

@@ -3,7 +3,7 @@
 {product_name} is a tool for building cloud-native workflow applications. You can use it to do the services and events orchestration and choreography. Currently, with {product_name} you can integrate with services and events in your architecture using:
 
 1. **CloudEvents**. Ideal for an Event-Driven architecture where the services are ready to consume and produce events working in a more reactive way.
-2. **Sync or Async REST services invocations via OpenAPI/Async API**. There are options even to directly call a REST service in the architecture or ecosystem. Either async or sync methods are supported depending on your requirements.
+2. **Sync or Async REST services invocations via OpenAPI/AsyncAPI**. There are options even to directly call a REST service in the architecture or ecosystem. Either async or sync methods are supported depending on your requirements.
 3. **Internal Service execution or invocation**. {product_name} is also a workflow framework to build applications. You can use it to create custom services in the same thread to run a lightweight workflow-based application within the same instance.
 
 You can learn how to create, manage, and deploy your workflow applications with the following guides.

serverlessworkflow/modules/ROOT/pages/job-services/core-concepts.adoc

@@ -394,13 +394,13 @@ And thus, the table above shows only a sub-set of all the available options. To
 == Eventing API
 
 The Job Service provides a Cloud Event based API that can be used to create and delete jobs.
-This API is useful in deployment scenarios where you want to use an event based communication from the workflow runtime to the Job Service. For the transport of these events you can use the <<knative-eventing, knative eventing>> system or the <<kafka-messaging, kafka messaging>> system.
+This API is useful in deployment scenarios where you want to use an event based communication from the workflow runtime to the Job Service. For the transport of these events you can use the <<knative-eventing, Knative eventing>> system or the <<kafka-messaging, kafka messaging>> system.
 
 [#knative-eventing]
 === Knative eventing
 
 By default, the Job Service Eventing API is prepared to work in a link:{knative_eventing_url}[Knative eventing] system. This means that by adding no additional configurations parameters, it'll be able to receive cloud events via the link:{knative_eventing_url}[Knative eventing] system to manage the jobs.
-However, you must still prepare your link:{knative_eventing_url}[Knative eventing] environment to ensure these events are properly delivered to the Job Service, see <<knative-eventing-supporting-resources, knative eventing supporting resources>>.
+However, you must still prepare your link:{knative_eventing_url}[Knative eventing] environment to ensure these events are properly delivered to the Job Service, see <<knative-eventing-supporting-resources, Knative eventing supporting resources>>.
 
 Finally, the only configuration parameter that you must set, when needed, is to enable the propagation of the Job Status Change events, for example, if you want to register these events in the {data_index_xref}[Data Index Service].
 
@@ -438,7 +438,7 @@ Using system properties with java like names::
 [#knative-eventing-supporting-resources]
 ==== Knative eventing supporting resources
 
-To ensure the Job Service receives the knative events to manage the jobs, you must create the <<knative-eventing-supporting-resources-trigger-create, create job events>> and <<knative-eventing-supporting-resources-trigger-delete, delete job events>> triggers shown in the diagram below.
+To ensure the Job Service receives the Knative events to manage the jobs, you must create the <<knative-eventing-supporting-resources-trigger-create, create job events>> and <<knative-eventing-supporting-resources-trigger-delete, delete job events>> triggers shown in the diagram below.
 Additionally, if you have enabled the Job Status Change events propagation you must create the <<knative-eventing-supporting-resources-sink-binding, sink binding>>.
 
 .Knative eventing supporting resources