Brought api v1 doc style (removed direct speech) in line with api v2 and made various small fixes to the content of both

Author: jaboehri

docs/src/process-development/api-v1/bpmn/messaging.md

@@ -4,21 +4,21 @@ icon: creative
 ---
 
 
-### Messaging
+## Messaging
 
-In order to enable communication with other lanes, pools or even entirely separate processes you need to be able to exchange information. In BPMN, you can use [Message Events](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/message-events/) to model this information exchange. Modeling communication with [Message Events](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/message-events/) in the same diagram uses Message Flow. Message Flow is typically represented by a dashed line arrow between BPMN elements with a black (send) or white (receive) envelope icon. The following BPMN collaboration diagram shows message exchange between two processes.
+Enabling communication with other lanes, pools or even entirely separate processes requires the ability to exchange information. In BPMN, [Message Events](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/message-events/) are used to model this information exchange. Modeling communication with [Message Events](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/message-events/) in the same diagram uses Message Flow. Message Flow is typically represented by a dashed line arrow between BPMN elements with a black (send) or white (receive) envelope icon. The following BPMN collaboration diagram shows message exchange between two processes.
 
 ![BPMN collaboration diagram with two processes using message flow to exchange information between two organizations](/photos/developer-documentation/message_flow.svg)
 
-#### Message Start Event
+### Message Start Event
 
-[Message Start Events](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/message-events/#message-start-event) allow a BPMN process to be started by an incoming message. In the DSF, all BPMN processes are started via messages. Therefore, you will have to include a [Message Start Event](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/message-events/#message-start-event) at the beginning of all of your BPMN models.
+[Message Start Events](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/message-events/#message-start-event) allow a BPMN process to be started by an incoming message. In the DSF, all BPMN processes are started via messages. Therefore, a [Message Start Event](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/message-events/#message-start-event) has to be included at the beginning of all of your BPMN models.
 
-#### Message Intermediate Throwing Event
+### Message Intermediate Throwing Event
 [Message Intermediate Throwing Events](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/message-events/#message-intermediate-throwing-event) are used to send messages during process execution.
 
-#### Message Intermediate Catching Event
-[Message Intermediate Catching Events](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/message-events/#message-intermediate-catching-event) serve as the counterpart to [Message Intermediate Throwing Events](messaging.md#message-intermediate-throwing-event). Use them whenever you expect to receive a message from another process or organization during execution.
+### Message Intermediate Catching Event
+[Message Intermediate Catching Events](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/message-events/#message-intermediate-catching-event) serve as the counterpart to [Message Intermediate Throwing Events](messaging.md#message-intermediate-throwing-event). Use them whenever it is expected to receive a message from another process or organization during execution.
 
-#### Message End Event
+### Message End Event
 The [Message End Event](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/message-events/#message-end-event) will stop the execution of a BPMN process and finish by sending a message.

docs/src/process-development/api-v1/bpmn/sequence-flow.md

@@ -3,5 +3,5 @@ title: Sequence Flow
 icon: creative
 ---
 
-### Sequence Flow
+## Sequence Flow
 BPMN 2.0 calls the continuous arrows connecting the BPMN elements in BPMN models, Sequence Flow. Sequence Flow exits one BPMN element and points at the next BPMN element to be processed.

docs/src/process-development/api-v1/bpmn/service-tasks.md

@@ -3,6 +3,6 @@ title: Service Tasks
 icon: creative
 ---
 
-### Service Tasks
+## Service Tasks
 
-One of the most common types of BPMN Tasks used for modeling DSF processes is the [Service Task](https://docs.camunda.org/manual/7.21/reference/bpmn20/tasks/service-task/). They are different from regular BPMN Tasks in that they offer the ability to link an implementation to the [Service Task](https://docs.camunda.org/manual/7.21/reference/bpmn20/tasks/service-task/) which can be called and executed by a BPMN engine. The BPE (Business Process Engine) server of the DSF leverages this engine to execute your BPMN processes.
+One of the most common types of BPMN Tasks used for modeling DSF processes is the [Service Task](https://docs.camunda.org/manual/7.21/reference/bpmn20/tasks/service-task/). They are different from regular BPMN Tasks in that they offer the ability to link an implementation to the [Service Task](https://docs.camunda.org/manual/7.21/reference/bpmn20/tasks/service-task/) which can be called and executed by a BPMN engine. The BPE (Business Process Engine) server of the DSF leverages this engine to execute BPMN processes.

docs/src/process-development/api-v1/bpmn/timer-intermediate-catching-events.md

@@ -3,6 +3,6 @@ title: Timer Intermediate Catching Events
 icon: creative
 ---
 
-### Timer Intermediate Catching Events
+## Timer Intermediate Catching Events
 
-A [Timer Intermediate Catching Event](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/timer-events/#timer-intermediate-catching-event) allows you to model stopwatch behavior. A timer is started once the BPMN execution arrives at the event. The duration until the timer runs out is specified using the [ISO 8601 Durations](http://en.wikipedia.org/wiki/ISO_8601#Durations) format. Examples can be found [here](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/timer-events/#time-duration). After running out, the BPMN process executes the [Sequence Flow](sequence-flow.md) following the [Timer Intermediate Catching Event](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/timer-events/#timer-intermediate-catching-event).
+A [Timer Intermediate Catching Event](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/timer-events/#timer-intermediate-catching-event) allows for modelling stopwatch behavior. A timer is started once the BPMN execution arrives at the event. The duration until the timer runs out is specified using the [ISO 8601 Durations](http://en.wikipedia.org/wiki/ISO_8601#Durations) format. Examples can be found [here](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/timer-events/#time-duration). After running out, the BPMN process executes the [Sequence Flow](sequence-flow.md) following the [Timer Intermediate Catching Event](https://docs.camunda.org/manual/7.21/reference/bpmn20/events/timer-events/#timer-intermediate-catching-event).

docs/src/process-development/api-v1/bpmn/user-tasks.md

@@ -3,6 +3,6 @@ title: User Tasks
 icon: creative
 ---
 
-### User Tasks
+## User Tasks
 
-User Tasks define a process step that requires some kind of human interaction. Usually this is done by providing some kind of form the user can fill out. The Camunda Modeler allows to configure these forms as either a propriatary format called [Camunda Forms](https://docs.camunda.io/docs/guides/utilizing-forms/) or custom forms called `Embedded or External Task Forms`. The DSF uses such `External Task Forms` in the form of [Questionnaire](https://www.hl7.org/fhir/R4/questionnaire.html) and [Questionnaire Response](https://www.hl7.org/fhir/R4/questionnaireresponse.html) resources. This mechanism is further expanded upon in [User Tasks in the DSF](../guides/user-tasks-in-the-dsf.md).
+User Tasks define a process step that requires some kind of human interaction. Usually this is done by providing some kind of form the user can fill out. The Camunda Modeler allows to configure these forms as either a proprietary format called [Camunda Forms](https://docs.camunda.io/docs/guides/utilizing-forms/) or custom forms called `Embedded or External Task Forms`. The DSF uses such `External Task Forms` in the form of [Questionnaire](https://www.hl7.org/fhir/R4/questionnaire.html) and [Questionnaire Response](https://www.hl7.org/fhir/R4/questionnaireresponse.html) resources. This mechanism is further expanded upon in [User Tasks in the DSF](../guides/user-tasks-in-the-dsf.md).

docs/src/process-development/api-v1/dsf/bpmn-process-execution.md

@@ -3,6 +3,6 @@ title: BPMN Process Execution
 icon: creative
 ---
 
-### BPMN Process Execution
+## BPMN Process Execution
 
-The BPMN process execution is the in-memory representation of a running BPMN process. BPMN processes have their executions structured as a tree hierarchy. Each BPMN process starts with the [process instance](https://docs.camunda.org/manual/7.21/user-guide/process-engine/process-engine-concepts/#process-instances) as its root level execution. If, for example, this root execution reaches a parallel gateway with two paths, it would spawn two child executions under itself for them to process all tasks along their paths on their own. Executions can access all the BPMN elements from the BPMN model as well as the [BPMN process variables](bpmn-process-variables.md). You have access to this representation in your Java code through the `execution` parameter when overriding certain methods in [Service](service-delegates.md) / [Message](message-delegates.md) Delegates like `execute` or `getAdditionalInputParameters` through the `variables` parameter.
+The BPMN process execution is the in-memory representation of a running BPMN process. BPMN processes have their executions structured as a tree hierarchy. Each BPMN process starts with the [process instance](https://docs.camunda.org/manual/7.21/user-guide/process-engine/process-engine-concepts/#process-instances) as its root level execution. If, for example, this root execution reaches a parallel gateway with two paths, it would spawn two child executions under itself for them to process all tasks along their paths on their own. Executions can access all the BPMN elements from the BPMN model as well as the [BPMN process variables](bpmn-process-variables.md). Access to this representation in the Java code is provided through the `execution` parameter when overriding certain methods in [Service](service-delegates.md) / [Message](message-delegates.md) Delegates like `execute` or `getAdditionalInputParameters`.

docs/src/process-development/api-v1/dsf/bpmn-process-variables.md

@@ -3,8 +3,8 @@ title: BPMN Process Variables
 icon: creative
 ---
 
-### BPMN Process Variables
+## BPMN Process Variables
 
 BPMN process variables hold additional information which has to be available during BPMN process execution. Variables can be directly related to BPMN elements like the boolean value for [Conditions](../bpmn/conditions.md), but do not have to be. BPMN process variables are stored as key-value pairs with the key being the variable name. They are accessible during the entirety of the execution to all [Service](service-delegates.md) / [Message](message-delegates.md) Delegates.
 
-You can learn how to access to the BPMN process variables [here](../guides/accessing-bpmn-process-variables.md).
+More information on how to access to the BPMN process variables is found in the guide on accessing [BPMN process variables](../guides/accessing-bpmn-process-variables.md).

docs/src/process-development/api-v1/dsf/draft-task-resources.md

@@ -3,9 +3,9 @@ title: Draft Task Resources
 icon: creative
 ---
 
-### Draft Task Resources
+## Draft Task Resources
 
-[Task](../fhir/task.md) resources with status `draft` are used to create the DSF FHIR server's functionality of starting processes via its web interface. They are stored in `.../tutorial-process/src/main/resources/fhir/Task`. Compared to regular [Task](../fhir/task.md) resources used to start BPMN processes, this type of [Task](../fhir/task.md) resource requires the status `draft` instead the usual `requested`. It also replaces the value for `authoredOn` with the placeholder `#{date}`, the values of organization identifiers with the placeholder `#{organization}` and all instances of version numbers with `#{version}`. Additionally, it requires setting the `Task.identifier` element. It should look something like this:
+[Task](../fhir/task.md) resources with status `draft` are used to create the DSF FHIR server's functionality of starting processes via its web interface. They are stored in `.../tutorial-process/src/main/resources/fhir/Task`. Compared to regular [Task](../fhir/task.md) resources used to start BPMN processes, this type of [Task](../fhir/task.md) resource requires the status `draft` instead of the usual `requested`. It also replaces the value for `authoredOn` with the placeholder `#{date}`, the values of organization identifiers with the placeholder `#{organization}` and all instances of version numbers with `#{version}`. Additionally, it requires setting the `Task.identifier` element. It should look something like this:
 
 ```xml
 <identifier>
@@ -14,8 +14,8 @@ icon: creative
 </identifier>
 ```
 `processKey` should be the same one used in [URLs](versions-placeholders-urls.md#urls).  
-`task-name` can be any String you wish to identify this task with. E.g. you can use the file name of the Draft Task.
+`task-name` can be any String this task should be identified with. E.g. you can use the file name of the Draft Task.
 
-For a complete example you can take a look at the Draft Task Resource in one of the solution branches and compare it to the one needed for cURL. The [Task](../fhir/task.md) resource created for cURL can be found at `.../tutorial-process/src/main/resources/example-task.xml`.
+A complete example for a Draft Task Resource can be found in the [Ping Pong Process Plugin](https://github.com/datasharingframework/dsf-process-ping-pong/blob/main/src/main/resources/fhir/Task/dsf-task-start-ping.xml).
 
-You might also want to check out [this guide](../guides/creating-task-resources-based-on-a-definition.md) if you do not know how to create [Task](../fhir/task.md) resources in general.
+There is also a [guide for creating task resources based on a StructureDefinition](../guides/creating-task-resources-based-on-a-definition.md) if more information on how to create [Task](../fhir/task.md) resources is required.

docs/src/process-development/api-v1/dsf/environment-variables.md

@@ -3,8 +3,8 @@ title: Environment Variables
 icon: creative
 ---
 
-### Environment Variables
+## Environment Variables
 
-Environment variables offer a way to make configuration data available at the start of a [BPMN process execution](bpmn-process-execution.md). They are the same for all running process instances. They can be defined by adding a member variable with the [Spring-Framework @Value](https://docs.spring.io/spring-framework/docs/current/reference/html/core.html#beans-value-annotations) annotation to the configuration class `TutorialConfig`. The value of the annotation uses the `${..}` notation and follows the form `${some.property:defaultValue}`, where each dot in the property name corresponds to an underscore in the equivalent environment variable. Environment variables are always written upper-case. The property `some.property` therefore corresponds to the environment variable `SOME_PROPERTY`.
+Environment variables offer a way to make configuration data available at the start of a [BPMN process execution](bpmn-process-execution.md). They are the same for all running process instances. They can be defined by adding a member variable with the [Spring-Framework @Value](https://docs.spring.io/spring-framework/docs/current/reference/html/core.html#beans-value-annotations) annotation to any Spring managed bean. For the DSF, the most prominent are classes annotated with [`@Configuration`](https://docs.spring.io/spring-framework/reference/core/beans/java/configuration-annotation.html). The value of the annotation uses the `${..}` notation and follows the form `${some.property:defaultValue}`, where each dot in the property name corresponds to an underscore in the equivalent environment variable. Environment variables are always written upper-case. The property `some.property` therefore corresponds to the environment variable `SOME_PROPERTY`.
 
-The DSF provides a feature to automatically generate documentation of environment variables during the Maven build process. You can use the `@ProcessDocumentation` annotation to automatically generate Markdown documentation for all fields with this annotation. You simply have to add [dsf-tools-documentation-generator](https://mvnrepository.com/artifact/dev.dsf/dsf-tools-documentation-generator) as a maven plugin. You can take a look at the `pom.xml` for the `tutorial-process` submodule [here](https://github.com/datasharingframework/dsf-process-tutorial/blob/main/tutorial-process/pom.xml) to see how you can add it to your own project. Keep in mind to point the `<workingPackage>` field to the package you want documentation for.
+The DSF provides a feature to automatically generate documentation of environment variables during the Maven build process. The `@ProcessDocumentation` annotation can be used to automatically generate Markdown documentation for all fields with this annotation. This requires adding [dsf-tools-documentation-generator](https://mvnrepository.com/artifact/dev.dsf/dsf-tools-documentation-generator) as a maven plugin. There is an example `pom.xml` for the `tutorial-process` submodule located on [GitHub](https://github.com/datasharingframework/dsf-process-tutorial/blob/main/tutorial-process/pom.xml) which uses the maven plugin. The `<workingPackage>` field has to point to the package where documentation is desired.