kie-kogito-docs#695: Holistic review follow-up (#698)

* Enhance install-serverless-operator guide

* Fix kn-plugin-workflow-overview

* Fix order of sections to reflect the users path

* Improve the introduction guide

* Add Exectuing a workflow procedure

* Slim down the testing section

serverlessworkflow/antora.yml

@@ -129,7 +129,7 @@ asciidoc:
     open_api_swagger_spec_url: https://swagger.io/docs/specification
     quarkus_openapi_gen_url: https://github.com/quarkiverse/quarkus-openapi-generator
     kn_workflow_plugin_releases_url: https://kie.apache.org/docs/start/download#sonataflow-knative-plugin
-    kie_tools_releases_page_url: https://github.com/apache/incubator-kie-tools/releases
+    kie_tools_releases_page_url: https://kie.apache.org/docs/start/download#sonataflow-knative-plugin
     quarkus_guides_base_url: https://quarkus.io/guides
     quarkus_guides_kafka_url: https://quarkus.io/guides/kafka
     quarkus_guides_building_native: https://quarkus.io/guides/building-native-image

serverlessworkflow/modules/ROOT/nav.adoc

@@ -22,7 +22,7 @@
 ** xref:getting-started/production-environment.adoc[]
 * Getting Started
 ** xref:getting-started/getting-familiar-with-our-tooling.adoc[]
-** xref:getting-started/create-your-first-workflow-service-with-kn-cli-and-vscode.adoc[]
+** xref:getting-started/introduction-sonataflow-development-guide.adoc[]
 ** xref:getting-started/java-embedded-workflows.adoc[]
 * Core Concepts
 ** xref:core/cncf-serverless-workflow-specification-support.adoc[]
@@ -44,29 +44,6 @@
 *** xref:tooling/serverless-logic-web-tools/serverless-logic-web-tools-openshift-integration.adoc[Integration with OpenShift]
 *** xref:tooling/serverless-logic-web-tools/serverless-logic-web-tools-redhat-application-services-integration.adoc[Integration with Service Registries]
 *** xref:tooling/serverless-logic-web-tools/serverless-logic-web-tools-deploy-projects.adoc[Deployment]
-* Service Orchestration
-** xref:service-orchestration/orchestration-of-openapi-based-services.adoc[OpenAPI]
-*** xref:service-orchestration/configuring-openapi-services-endpoints.adoc[Advanced Configuration]
-*** xref:service-orchestration/working-with-openapi-callbacks.adoc[Callbacks]
-** xref:service-orchestration/troubleshooting.adoc[Troubleshooting]
-* Event Orchestration
-** xref:eventing/orchestration-of-asyncapi-based-services.adoc[AsyncAPI]
-** xref:eventing/event-correlation-with-workflows.adoc[Event Correlation]
-* Security
-** Client Authentication
-*** xref:security/authention-support-for-openapi-services.adoc[OpenAPI Authentication]
-*** xref:security/orchestrating-third-party-services-with-oauth2.adoc[OpenAPI OAuth2]
-* Executing, Testing and Troubleshooting
-** Executing and Testing Workflows
-*** xref:testing-and-troubleshooting/quarkus-dev-ui-extension/quarkus-dev-ui-overview.adoc[Developer UI]
-**** xref:testing-and-troubleshooting/quarkus-dev-ui-extension/quarkus-dev-ui-workflow-instances-page.adoc[Workflow Instances]
-**** xref:testing-and-troubleshooting/quarkus-dev-ui-extension/quarkus-dev-ui-workflow-definition-page.adoc[Workflow Definitions]
-**** xref:testing-and-troubleshooting/quarkus-dev-ui-extension/quarkus-dev-ui-monitoring-page.adoc[Monitoring]
-**** xref:testing-and-troubleshooting/quarkus-dev-ui-extension/quarkus-dev-ui-custom-dashboard-page.adoc[Dashboards]
-*** xref:testing-and-troubleshooting/kn-plugin-workflow-overview.adoc[Command Line]
-* Persistence
-** xref:persistence/core-concepts.adoc[Core concepts]
-// * Java Workflow Library TODO: https://issues.redhat.com/browse/KOGITO-9454
 * xref:cloud/index.adoc[Cloud]
 ** xref:cloud/custom-ingress-authz.adoc[Securing Workflows]
 ** xref:cloud/deploying-sonataflow-management-console-on-kubernetes.adoc[Deploying Management Console on Kubernetes]
@@ -90,6 +67,28 @@
 **** xref:cloud/operator/sonataflow-metrics.adoc[Prometheus Metrics for Workflows]
 *** xref:cloud/operator/known-issues.adoc[Roadmap and Known Issues]
 *** xref:cloud/operator/add-custom-ca-to-a-workflow-pod.adoc[Add Custom CA to Workflow Pod]
+* Service Orchestration
+** xref:service-orchestration/orchestration-of-openapi-based-services.adoc[OpenAPI]
+*** xref:service-orchestration/configuring-openapi-services-endpoints.adoc[Advanced Configuration]
+*** xref:service-orchestration/working-with-openapi-callbacks.adoc[Callbacks]
+** xref:service-orchestration/troubleshooting.adoc[Troubleshooting]
+* Event Orchestration
+** xref:eventing/orchestration-of-asyncapi-based-services.adoc[AsyncAPI]
+** xref:eventing/event-correlation-with-workflows.adoc[Event Correlation]
+* Security
+** Client Authentication
+*** xref:security/authention-support-for-openapi-services.adoc[OpenAPI Authentication]
+*** xref:security/orchestrating-third-party-services-with-oauth2.adoc[OpenAPI OAuth2]
+* Executing, Testing and Troubleshooting
+** xref:testing-and-troubleshooting/kn-plugin-workflow-overview.adoc[KN CLI Workflow plugin]
+** xref:testing-and-troubleshooting/quarkus-dev-ui-extension/quarkus-dev-ui-overview.adoc[Developer UI]
+*** xref:testing-and-troubleshooting/quarkus-dev-ui-extension/quarkus-dev-ui-workflow-instances-page.adoc[Workflow Instances]
+*** xref:testing-and-troubleshooting/quarkus-dev-ui-extension/quarkus-dev-ui-workflow-definition-page.adoc[Workflow Definitions]
+*** xref:testing-and-troubleshooting/quarkus-dev-ui-extension/quarkus-dev-ui-monitoring-page.adoc[Monitoring]
+*** xref:testing-and-troubleshooting/quarkus-dev-ui-extension/quarkus-dev-ui-custom-dashboard-page.adoc[Dashboards]
+* Persistence
+** xref:persistence/core-concepts.adoc[Core concepts]
+// * Java Workflow Library TODO: https://issues.redhat.com/browse/KOGITO-9454
 * Integrations
 ** xref:integrations/core-concepts.adoc[]
 * Job Service
@@ -98,7 +97,7 @@
 ** xref:data-index/data-index-core-concepts.adoc[Core concepts]
 ** xref:data-index/data-index-service.adoc[Standalone service]
 * Use Cases
-** xref:use-cases/advanced-developer-use-cases/index.adoc[Advanced Development Use Cases of {product_name} applications using Quarkus and Java]
+** xref:use-cases/advanced-developer-use-cases/index.adoc[{product_name} applications development using Quarkus and Java]
 *** Getting started
 **** xref:use-cases/advanced-developer-use-cases/getting-started/create-your-first-workflow-service.adoc[]
 **** xref:use-cases/advanced-developer-use-cases/getting-started/create-your-first-workflow-project.adoc[]

serverlessworkflow/modules/ROOT/pages/_common-content/getting-started-requirement.adoc

@@ -1,3 +1,3 @@
 * A workflow project is created.
 +
-For more information about creating a workflow project, see xref:getting-started/create-your-first-workflow-service-with-kn-cli-and-vscode.adoc[Creating your first workflow project].
+For more information about creating a workflow project, see xref:getting-started/introduction-sonataflow-development-guide.adoc[Creating your first workflow project].

serverlessworkflow/modules/ROOT/pages/cloud/operator/install-serverless-operator.adoc

@@ -5,13 +5,14 @@
 :keywords: kogito, sonataflow, workflow, serverless, operator, kubernetes, minikube, openshift, containers
 // links
 
+:kubernetes_version: {kubernetes_version}
 :openshift_operator_install_url: https://docs.openshift.com/container-platform/4.13/operators/admin/olm-adding-operators-to-cluster.html
 :openshift_operator_uninstall_url: https://docs.openshift.com/container-platform/4.13/operators/admin/olm-deleting-operators-from-cluster.html
 :kubernetes_operator_install_url: https://operatorhub.io/how-to-install-an-operator
 :kubernetes_operator_uninstall_url: https://olm.operatorframework.io/docs/tasks/uninstall-operator/
 :operatorhub_url: https://operatorhub.io/
 
-This guide describes how to install the {operator_name} in a Kubernetes or OpenShift cluster. The operator is in an xref:cloud/operator/known-issues.adoc[early development stage] (community only) and has been tested on OpenShift {openshift_version_min}+, Kubernetes {kubernetes_version}+, and link:{minikube_url}[Minikube].
+This guide describes how to install the {operator_name} in a Kubernetes or OpenShift cluster. The operator is in an xref:cloud/operator/known-issues.adoc[early development stage] (community only) and has been tested on OpenShift {openshift_version_min}+ , Kubernetes {kubernetes_version}+ , {minikube_url}[Minikube] and {kind_install_url}[Kind].
 
 .Prerequisites
 * A Kubernetes or OpenShift cluster with admin privileges and `kubectl` installed. 
@@ -64,7 +65,9 @@ To install the {product_name} Operator, you can use the following command:
 ----
 kubectl create -f {kogito_operator_repository_rawcontent_url}/{operator_version}/operator.yaml
 ----
+
 Replace `<version>` with specific version if needed:
+[source,shell,subs="attributes+"]
 ----
 kubectl create -f {kogito_operator_repository_rawcontent_url}/<version>/operator.yaml
 ----
@@ -120,8 +123,14 @@ To uninstall the correct version of the operator, first you must get the current
 .Getting the operator version
 [source,shell,subs="attributes+"]
 ----
-kubectl get deployment {operator_controller_manager_deployment_name} -n sonataflow-operator-system -o jsonpath="{.spec.template.spec.containers[?(@.name=='manager')].image}"
+kubectl get deployment {operator_controller_manager_deployment_name} \
+    -n sonataflow-operator-system \
+    -o jsonpath="{.spec.template.spec.containers[?(@.name=='manager')].image}"
+----
 
+Expected output:
+[source,shell,subs="attributes+"]
+----
 {sonataflow_operator_imagename}:{operator_version}
 ----
 

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

@@ -266,7 +266,7 @@ Secrets are associated with the link:{quarkus_config_guide_url}[Quarkus Configur
 
 == Additional resources
 
-* xref:getting-started/create-your-first-workflow-service-with-kn-cli-and-vscode.adoc[]
+* xref:getting-started/introduction-sonataflow-development-guide.adoc[]
 * xref:getting-started/getting-familiar-with-our-tooling.adoc[Getting familiar with {product_name} tooling]
 
 include::../../pages/_common-content/report-issue.adoc[]

serverlessworkflow/modules/ROOT/pages/core/understanding-workflow-error-handling.adoc

@@ -185,7 +185,7 @@ The `finish` state in the `serverless-workflow-error-quarkus` example applicatio
 
 == Additional resources
 
-* xref:getting-started/create-your-first-workflow-service-with-kn-cli-and-vscode[]
+* xref:getting-started/introduction-sonataflow-development-guide[]
 
 include::../../pages/_common-content/report-issue.adoc[]
 

serverlessworkflow/modules/ROOT/pages/core/working-with-callbacks.adoc

@@ -17,7 +17,7 @@ The workflow correlation described in this document focuses on the former mechan
 
 == Additional resources
 
-* xref:getting-started/create-your-first-workflow-service-with-kn-cli-and-vscode.adoc[]
+* xref:getting-started/introduction-sonataflow-development-guide.adoc[]
 * xref:eventing/event-correlation-with-workflows.adoc[Event correlation in {product_name}]
 * xref:use-cases/advanced-developer-use-cases/callbacks/callback-state-example.adoc[]
 * xref:use-cases/advanced-developer-use-cases/getting-started/create-your-first-workflow-service.adoc[]

serverlessworkflow/modules/ROOT/pages/core/working-with-parallelism.adoc

@@ -270,6 +270,6 @@ The parallel workflow data shows the concatenated string as result, but in this
 
 == Additional resources
 
-* xref:getting-started/create-your-first-workflow-service-with-kn-cli-and-vscode.adoc[Creating your first workflow service]
+* xref:getting-started/introduction-sonataflow-development-guide.adoc[Creating your first workflow service]
 
 include::../../pages/_common-content/report-issue.adoc[]

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

@@ -1,69 +1,116 @@
-= Creating and running workflow projects using KN CLI and Visual Studio Code
+= Introduction to {product_name} development
 
-This guide showcases using the Knative Workflow CLI plugin and Visual Studio code to create & run {product_name} projects.
+This guide showcases the {product_name} Workflow CLI plugin and Apache KIE Serverless Workflow Visual Studio code extension to create, run & deploy {product_name} projects on your local environment and walks you trhought the recommended development loop of workflow applications.
 
 .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 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
+== Creating a workflow project with KN CLI
 
 Use the `create` command with kn workflow to scaffold a new SonataFlow project.
 
-* Navigate to your development directory and create your project.
+.Procedure
+. Navigate to your development directory and create your project.
 [source,bash]
++
 ----
 kn workflow create -n my-sonataflow-project
 ----
-* This will create a folder with name `my-sonataflow-project` and a sample workflow `workflow.sw.json`
+. This will create a folder with name `my-sonataflow-project` and a sample workflow `workflow.sw.json`
 [source,bash]
++
 ----
 cd ./my-sonataflow-project
 ----
-* Open the folder in Visual Studio Code and examine the created `workflow.sw.json` using our extension.
+. Open the folder in Visual Studio Code and examine or  the created `workflow.sw.json` using the editor provided by the extension. 
+[source,bash]
++
+----
+code workflow.sw.json
+----
 
 Now you can run the project and execute the workflow.
 
 [[proc-running-app-with-kn-cli]]
-== Running a Workflow project with Visual Studio Code and KN CLI
+== Running a workflow project with KN CLI
 
-Use the `run` command with kn workflow to build and run the {product_name} project in local development mode.
+Use the `run` command with kn workflow to build and run the {product_name} project locally in development mode.
 
-* Run the project.  
+.Procedure
+. Run the project.
++
 [source,bash]
 ----
 kn workflow run
 ----
 * The Development UI will be accessible at `localhost:8080/q/dev`
 * You can now work on your project. Any changes will be picked up by the hot reload feature.
 * See xref:testing-and-troubleshooting/quarkus-dev-ui-extension/quarkus-dev-ui-workflow-instances-page.adoc[Workflow instances] guide on how to run workflows via Development UI.
-* Once you are done developing your project navigate to the terminal that is running the `kn workflow run` command and hit `Ctlr+C` to stop the development environment.
+* Once you are done developing your project navigate to the terminal that is running the `kn workflow run` command and hit `Ctrl+C` to stop the development environment.
 
 You can use any editor to develop your workflow to suit your use case. We recommend getting familiar with xref:../core/cncf-serverless-workflow-specification-support.adoc[] and guides in `Core` chapter first. 
 
-To deploy the finished project to a local cluster, proceed to the next section.
+.Executing a workflow
+. To test your running workflow project, access the Swagger UI on `localhost:8080/q/swagger-ui` to examine available endpoints.
+. In order to execute the workflow once, run: 
+[source,bash]
+----
+curl -X 'POST' \
+  'localhost:8080/hello' \
+  -H 'accept: */*' \
+  -H 'Content-Type: application/json' \
+  -d '{
+  "workflowdata": {}
+}'
+----
+. You should see a similar response:
++
+[source,bash]
+----
+{"id": "<UUID>", "workflowdata" : {"message":"Hello World"}}
+----
+
+
+To deploy the finished project to kubernetes cluster, proceed to the next section.
 
 [[proc-deploying-app-with-kn-cli]]
-== Deploying a workflow project with Visual Studio Code and KN CLI
+== Deploying a workflow project with KN CLI
+
+.Prerequisites
+* You are logged into your kubernetes cluster or started one locally according to the xref:getting-started/preparing-environment.adoc#proc-starting-cluster-fo-local-development[starting cluster for local development] guide.
+* You have installed {operator_name} in your kubernetes cluster according to xref:cloud/operator/install-serverless-operator.adoc[operator installation] guide.
 
 Use the `deploy` command with kn workflow to deploy the {product_name} project into your local cluster.
 
-* Create a namespace for your application
+.Procedure
+. Create a namespace for your application
++
 [source,bash]
 ----
 kubectl create namespace my-sf-application
 ----
-* Deploy to cluster
+. Deploy the workflow to the cluster in the default `dev` mode. The plugin uses settings located in `./<home>/.kube/config` to access the cluster.
++
 [source,bash]
 ----
 kn workflow deploy --namespace my-sf-application
 ----
-* Using k9s cli you can examine your deployment.
 * In a separate bash instance create a port mapping:
 +
 [tabs]
 ====
+Openshift::
++
+--
+[source,shell]
+----
+oc get route svc/hello --namespace my-sf-application
+----
+* On openshift the route is generated for you in `dev` mode deployments. Use the URL of the generated route to access your workflow instances using the Developement interface.
+** <RETURNED_URL>{sonataflow_devmode_devui_url}workflows
+--
 Minikube::
 +
 --
@@ -93,38 +140,20 @@ kubectl port-forward service/hello <RANDOM_PORT>:80 -n my-sf-application
 --
 ====
 
-* To update the image, run the `deploy` again, note that this may take some time.
-* To stop the deployment, use the `undeploy` command:
+* To update the image, run the `deploy` again, note that this may take some time. You can also direcly edit the `Sonataflow` resource in the cluster. In `dev` mode, the operator will update the deployment with the changes.
+. To stop the deployment, use the `undeploy` command:
++
 [source,bash]
 ----
 kn workflow undeploy --namespace my-sf-application
 ----
-* You can validate your pod is terminating using k9s cli.
 
 [[proc-testing-application]]
 == Testing your workflow application
 
-To test your workflow application you can use any capable REST client out there. All that is needed is the URL of your deployed workflow project.
-
-.Prerequisites
-* You have your workflow project deployed using <<proc-deploying-app-with-kn-cli>> and you have the URL where it is deployed handy.
-
-.Testing your workflow application
-* To test your workflow project, access the Swagger UI on `<URL>/q/swagger-ui` to examine available endpoints.
-* In order to execute the workflow once, run: 
-[source,bash]
-----
-curl -X 'POST' \
-  '<URL>/hello' \
-  -H 'accept: */*' \
-  -H 'Content-Type: application/json' \
-  -d '{
-  "workflowdata": {}
-}'
-----
-* To examine executed instance you can use the GraphQL UI by navigating to
-`<URL>/q/graphl-ui`.
-
+To test your workflow application you can use any capable REST client out there. All that is needed is the URL of your deployed workflow project, which is showcase in section above,
+You can also use the management console provided as part of the development interface.
+Please see the additional resources to proceed.
 
 == Additional resources
 

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

@@ -102,6 +102,6 @@ Points listed in this section provide extra possibilities when working with our
 == Additional resources
 
 * xref:getting-started/production-environment.adoc[]
-* xref:getting-started/create-your-first-workflow-service-with-kn-cli-and-vscode.adoc[]
+* xref:getting-started/introduction-sonataflow-development-guide.adoc[]
 
 include::../../pages/_common-content/report-issue.adoc[]

serverlessworkflow/modules/ROOT/pages/index.adoc

@@ -49,7 +49,7 @@ Learn about the tools we provide you with, on your journey to create {product_na
 [.card]
 --
 [.card-title]
-xref:getting-started/create-your-first-workflow-service-with-kn-cli-and-vscode.adoc[]
+xref:getting-started/introduction-sonataflow-development-guide.adoc[]
 [.card-description]
 An all-in-one starting guide. Learn how to create, run & deploy your first {product_name} project on your local environment.
 --

serverlessworkflow/modules/ROOT/pages/service-orchestration/orchestration-of-openapi-based-services.adoc

@@ -16,7 +16,7 @@
 :mp_config_env_vars_url: https://github.com/eclipse/microprofile-config/blob/master/spec/src/main/asciidoc/configsources.asciidoc#environment-variables-mapping-rules
 // Referenced documentation pages.
 :getting-familiar-with-our-tooling: xref:getting-started/getting-familiar-with-our-tooling.adoc
-:create-your-first-workflow-service: xref:getting-started/create-your-first-workflow-service-with-kn-cli-and-vscode.adoc
+:create-your-first-workflow-service: xref:getting-started/introduction-sonataflow-development-guide.adoc
 :build-workflow-image-with-quarkus-cli: xref:use-cases/advanced-developer-use-cases/getting-started/build-workflow-image-with-quarkus-cli.adoc
 :understanding-jq-expressions: xref:core/understanding-jq-expressions.adoc
 :configuring-openapi-services-endpoints: xref:service-orchestration/configuring-openapi-services-endpoints.adoc