Process applications pages content

docs/components/modeler/web-modeler/create-a-process-application.md

@@ -7,9 +7,6 @@ description: Create a process application.
 import EmptyProjectImg from './img/process-applications/empty-project.png'
 import ReassignMainProcessImg from './img/process-applications/reassign-main-process.png'
 import FileListImg from './img/process-applications/file-list.png'
-import DeployProcessApplicationImg from './img/process-applications/deploy-process-application.png'
-import RunProcessApplicationImg from './img/process-applications/run-process-application.png'
-import DeployErrorImg from './img/process-applications/deploy-error.png'
 
 Get started by creating a new process application.
 
@@ -19,8 +16,7 @@ To create a process application, either:
 
 - Select **Create process application** in an empty project.
 - Select **New project > Create process application** if you have not yet created a project.
-
-<p><img src={EmptyProjectImg} alt="Create a process application from an empty project" /></p>
+  <p><img src={EmptyProjectImg} alt="Create a process application from an empty project" /></p>
 
 ### Select a default cluster
 
@@ -35,7 +31,7 @@ When you create a process application, you must select a development cluster to
 
 - If your modeling plan does not allow you to create more clusters, a `Cluster creation is not available on this modeling plan` warning is shown. Contact the administrator or owner of your organization to upgrade your plan.
 
-- A `Missing permissions` warning is shown if you do not have the proper permissions to create a cluster. Contact the administrator or owner of your organization to create a cluster.
+- If you do not have the proper permissions to create a cluster, a `Missing permissions` warning is shown. Contact the administrator or owner of your organization to create a cluster.
 
 :::
 
@@ -44,7 +40,7 @@ When you create a process application, you must select a development cluster to
 After you have created a process application, a new BPMN diagram is created and labeled as the main process.
 
 - The main process diagram is named using the process application name. You can rename the main process diagram any time.
-- A process application must always have a main process. The main process diagram cannot be deleted or moved out of the process application.
+- A process application must have a main process. You cannot delete or move the main process diagram out of the process application.
 - You can assign another BPMN diagram as the main process using the **Reassign main process** option in the action menu.
   <p>
   <img src={ReassignMainProcessImg} alt="Reassign the main process" />

docs/components/modeler/web-modeler/deploy-process-application.md

@@ -1,70 +1,57 @@
 ---
 id: deploy-process-application
 title: Deploy and run your process application
-description: You can deploy your process application to a Zeebe cluster, and run a new process instance.
+description: You can deploy your process application to a Zeebe cluster, or run your process application to test and debug it, and observe how it performs in a live environment..
 ---
 
-import EmptyProjectImg from './img/process-applications/empty-project.png'
-import ReassignMainProcessImg from './img/process-applications/reassign-main-process.png'
-import FileListImg from './img/process-applications/file-list.png'
-import DeployProcessApplicationImg from './img/process-applications/deploy-process-application.png'
+import DeployImg from './img/process-applications/define-stages-deploy.png'
 import RunProcessApplicationImg from './img/process-applications/run-process-application.png'
 import DeployErrorImg from './img/process-applications/deploy-error.png'
 
-You can deploy your process application to a Zeebe cluster, and run a new process instance.
+You can deploy your process application to a Zeebe cluster, and run your process application to test and debug it, and observe how it performs in a live environment.
 
 ## Deploy your process application
 
 To deploy your process application:
 
-1. Open the process application's [main process](create-a-process-application.md#main-process).
-1. Select **Deploy**.
-   - Turn on the toggle of the cluster stage you want to deploy to.
-   - Perform any other actions as required, such as unpausing the chosen cluster, or managing the cluster.
-1. Select **Deploy** to deploy the process application to the selected Zeebe cluster.
+1. Open the [main process](create-a-process-application.md#main-process).
+1. Select **Deploy** to open the **Deploy process application** modal.
+   <p><img src={DeployImg} alt="Deploy a process application" /></p>
+1. Turn on the toggle for the cluster stage you want to deploy to.
+1. Perform any other actions as required, such as:
+   - Unpausing the chosen cluster if it has been auto-paused. Select **Resume**.
+   - Managing the cluster. Select **Manage**.
+   - [Defining the stages](process-application-pipeline.md#deployment-stages) of your development pipeline. Select **Define stages**.
+1. Select **Deploy** to deploy the process application to the selected cluster.
 
-<p><img src={DeployProcessApplicationImg} alt="Deploy a process application" /></p>
-
-All BPMN, DMN, and form files contained in the process application folder will be deployed in a single bundle.
+All BPMN, DMN, and form files contained in the process application folder are deployed as a single bundle.
 
 :::note
-If any resource fails to deploy, the whole deployment will [fail](#deployment-errors) and the cluster state will remain unchanged.
-This ensures that a process application cannot be deployed incompletely or in an inconsistent state, making it safer to use.
+If any resource fails to deploy, the whole deployment [fails](#deployment-errors) and the cluster state remains unchanged. This safely ensures that a process application cannot be deployed incompletely or in an inconsistent state.
 :::
 
-Note that when you select **Deploy**, you may also select **Define stages** to set up a pipeline for development, and the promotion from one stage to another of a given process application version:
-
-![define stages when deploying modal](./img/process-applications/define-stages-deploy.png)
-
-Here, you can select the applicable cluster for development, testing, staging, and production:
-
-![define stage for deployment modal](./img/process-applications/define-stages.png)
-
-If no cluster is selected for at least one stage, a warning may appear reading **Undefined stages**. To deploy, you must define clusters for your stages.
-
 ## Run a process application
 
-Open the process application's [main process](#main-process) and use the **Run** button to start a new instance.
-Before the actual process instance is started, all resources will be re-deployed if required so the new instance
-will always use their latest state.
+You can run your process application to test and debug it, and observe how it performs in a live environment.
 
-<p><img src={RunProcessApplicationImg} alt="Run a process application" /></p>
+To run your process application:
 
-After the process instance is started, you will receive a notification with a link to the process instance view in
-[Operate](../../operate/operate-introduction.md).
-Follow this link to monitor the process instance and interact with it as needed.
+1. Open the [main process](create-a-process-application.md#main-process).
+1. Select **Run** to open the **Start instance** modal.
+   <p><img src={RunProcessApplicationImg} alt="Run a process application" /></p>
+1. Select **Run** to start a new instance.<p><ul><li>Before the actual process instance is started, all resources are re-deployed if required so the new instance
+   always uses their latest state.</li><li>After the process instance is started, you will receive a notification with a link to the process instance view in
+   [Operate](../../operate/operate-introduction.md). Open this link to monitor the process instance.</li></ul></p>
 
 :::info
-Single-file deployment is not supported in a process application.
-If you click the **Deploy** or **Run** button for any diagram other than the main process, you will be asked to open the
-main process instead to deploy the whole process application from there.
+Single-file deployment is not supported in a process application. If you select **Deploy** or **Run** in any diagram other than the main process, you are prompted to open the main process for deployment.
 :::
 
 ## Deployment errors
 
-If the deployment of a process application fails (for example, because one or more of the contained resources have invalid
-implementation properties), a modal containing the error message thrown by the Zeebe engine will be displayed.
-The message usually comprises the name of the affected resource, the ID of the invalid diagram element, and the actual error.
+If the deployment of a process application fails (for example, because one or more of the contained resources has invalid implementation properties), a modal is shown containing the error message thrown by the Zeebe engine.
+
+The message typically provides the name of the affected resource, the ID of the invalid diagram element, and the error details.
 
 <p><img src={DeployErrorImg} style={{width: 680}} alt="Process application deployment error" /></p>
 

docs/components/modeler/web-modeler/process-application-pipeline.md

@@ -5,8 +5,9 @@ description: The Web Modeler provides a lightweight development pipeline you can
 ---
 
 import DeployProcessApplicationDiagramImg from './img/process-applications/diagram-process-application-pipeline.png'
+import DeployStagesImg from './img/process-applications/define-stages.png'
 
-The Web Modeler provides a lightweight development pipeline you can use to quickly develop and progress low-risk process application releases through the stages of a standard development life cycle.
+You can use the provided Web Modeler development pipeline to quickly develop and progress low-risk process application releases through the stages of a standard development life cycle.
 
 <p><img src={DeployProcessApplicationDiagramImg} alt="Process application file list" /></p>
 
@@ -16,19 +17,35 @@ For business-critical and higher-risk processes that require strict governance a
 
 ## Model
 
-If you choose to use this pipeline, the following features are helpful during design and modeling.
+During the modeling stage, you will typically:
 
-- Use token simulation to correct and optimize your process flow.
-- Use Play mode to quickly validate the process behavior after you have added implementation details.
-- Use versioning to track and review changes across assets in the process application.
-  - For example, visually review changes between two versions of a BPPMN file, or view code changes for other files.
-  - Add a comment to the main process diagram to indicate that a review is complete and that the process application can be promoted to the next stage.
+- [Create a process application](create-a-process-application.md) and select a default development cluster to deploy to.
+- Invite other users to collaborate on the process application.
+- Define and setup the clusters and deployment stages that you will use in your development pipeline.
+- Model your diagrams and any associated resources, and fix any errors shown in the modeler.
 
 ### Deployment stages
 
-When you create a process application, you select a default development cluster to deploy to during development.
+You can deploy and promote an application process version between the stages of a standard development life cycle (development, testing, staging, production).
 
-You can also choose to define and deploy to different stages/clusters, allowing you to promote an application process version between stages in a development life cycle. You can define and deploy to the following stages:
+To define your pipeline cluster stages:
+
+1. Open the [main process](create-a-process-application.md#main-process).
+1. Select **Deploy** to open the **Deploy process application** modal.
+1. Select **Define stages** to open the **Define stages** modal.
+   <p><img src={DeployStagesImg} alt="Define stage for deployment modal" /></p>
+1. Select and assign a cluster to each deployment stage that you want to use in your pipeline.
+1. Select **Save** to save your changes and close the modal.
+
+:::note
+
+- An administrator should typically define the stages and clusters within Web Modeler.
+- During deployment, the next stage is not automatically selected. You must choose the stage you want to promote to.
+- You must select a cluster for at least one stage to be able to deploy. An **Undefined stages** warning is shown if no cluster is selected for at least one stage.
+
+:::
+
+You can define and deploy to the following stages:
 
 | Stage       | Description                                                                                                     |
 | :---------- | :-------------------------------------------------------------------------------------------------------------- |
@@ -37,24 +54,35 @@ You can also choose to define and deploy to different stages/clusters, allowing
 | Staging     | Use for controlled testing where changes are validated before deployment to production.                         |
 | Production  | The live system with the latest software. Only administrators and organization owners can deploy to this stage. |
 
-:::note
-
-- An administrator should define the stages and clusters within Web Modeler.
-- During deployment, the next stage is not automatically selected. You must choose the stage you want to promote to.
+## Validate
 
-:::
+When your process application is ready for validation you can deploy it to your development cluster.
 
-## Validate
+- Use [Play mode](play-your-process.md) to quickly validate the process behavior and play different scenarios.
+- Use [token simulation](token-simulation.md) to correct and optimize your process flow.
+- Validate that all files and resources are correctly deployed.
 
 ## Review
 
+After validation is complete, you can release a version of your process application for review and approval.
+
+- Use [process application versioning](process-application-versioning.md) to track and review changes across the files and assets in the process application. You can [compare milestones](/docs/components/modeler/web-modeler/milestones.md#compare-milestones) to visually review changes between two versions of a BPMN file, or view code changes for other files.
+- Use comments to make review collaboration easier.
+- Approvers can add a comment to the main process diagram to indicate that a review is complete and that the process application is ready to be promoted to the next stage.
+
 ## Promote
 
+After the review is complete, you can promote the versioned process application to the next stage(s). For example, promote to your testing cluster/stage, then to staging, and finally to your production environment.
+
+:::info
+If you want to use your own development pipeline after the review is complete, you can use [Git Sync](git-sync.md) at this point to deploy and promote this version of the process application through your own pipeline stages and environment.
+:::
+
 ## Process governance
 
 The Web Modeler development pipeline offers the following process governance:
 
-| Governance         | Description                                                                                                                                                                                                                                                                                                     |
-| :----------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Change control     | Users can announce a review is complete by adding a comment to the main process diagram.                                                                                                                                                                                                                        |
-| Deployment control | <p><ul><li><p>Deployments can only be made to the pre-defined set of approved clusters.</p></li><li>Only users with the right privileges can deploy, and only org admins can deploy to prod-tagged clusters.</li><li>Each deployment action is logged with the user and stage it was deployed to.</li></ul></p> |
+| Governance         | Description                                                                                                                                                                                                                                                                                                                                     |
+| :----------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Change control     | Users can announce a review is complete by adding a comment to the main process diagram.                                                                                                                                                                                                                                                        |
+| Deployment control | <p><ul><li><p>Deployments can only be made to the pre-defined set of approved clusters.</p></li><li>Only users with correct privileges can deploy, and only organization administrators can deploy to `prod` tagged clusters.</li><li>Each deployment action is logged with information on the user and stage it was deployed to.</li></ul></p> |

docs/components/modeler/web-modeler/process-application-versioning.md

@@ -30,7 +30,7 @@ To create a bulk milestone for a process application:
 
 ![Create a milestone screen](img/milestones/web-modeler-milestone-create-versioned-milestone-highlight.png)
 
-Now when you open the milestone history for any file in the process application, you can use the file navigation header buttons to switch between files, and view their individual milestone history.
+Now when you open the milestone history for any file in the process application, you can use the file navigation header buttons to switch between files, and view their individual milestone history. See [compare milestones](/docs/components/modeler/web-modeler/milestones.md#compare-milestones).
 
 ![Milestone history with file navigation header buttons highlighted](img/milestones/web-modeler-milestone-compare-process-application-files-highlight.png)