Update to 'SubFlow State' spec doc (#141)

* Update to 'SubFlow State' spec doc

Signed-off-by: Tihomir Surdilovic <[email protected]>

* Updates - remove standalone flag, remove function/event inheritance

Signed-off-by: Tihomir Surdilovic <[email protected]>

Author: Tihomir Surdilovic

media/spec/subflowstateref.png

@@ -1897,11 +1897,11 @@ For more information, see the [workflow error handling and retrying section](#wo
 | id | Unique state id | string | no |
 | name |State name | string | yes |
 | type |State type | string | yes |
-| waitForCompletion |If workflow execution must wait for sub-workflow to finish before continuing | boolean | yes |
+| waitForCompletion | If workflow execution must wait for sub-workflow to finish before continuing | boolean | yes |
 | workflowId |Sub-workflow unique id | boolean | no |
 | [stateDataFilter](#state-data-filter) | State data filter | object | no |
 | [onError](#Workflow-Error-Handling) | States error handling definitions | array | no |
-| [transition](#Transitions) |Next transition of the workflow after subflow has completed | object | yes (if end is not defined) |
+| [transition](#Transitions) | Next transition of the workflow after subflow has completed | object | yes (if end is not defined) |
 | dataInputSchema | URI to JSON Schema that state data input adheres to | string | no |
 | dataOutputSchema | URI to JSON Schema that state data output adheres to | string | no |
 | [metadata](#Workflow-Metadata) | Metadata information| object | no |
@@ -1947,27 +1947,28 @@ end:
 
 </details>
 
-It is often the case that you want to group your workflows into small, reusable logical units that perform certain needed functionality.
-Even though you can use the Event or Callback states to call externally deployed services (via function), at times
-there is a need to include/inject another serverless workflow (from classpath/local file system etc, depending on the implementation logic).
-In that case you would use the SubFlow state.
-It also allows developers to model their workflows with reusability and logical grouping in mind.
+Often you want to group your workflows into small logical units that solve a particular business problem and can be reused in 
+multiple other workflow definitions.
 
-This state allows developers to include/inject a uniquely identified sub-workflow and start its execution.
-Another use of this state is within [branches](#parallel-state-branch) of the [Parallel State](#Parallel-State). 
-Instead of having to define all states
-in each branch, you could separate the branch states into individual sub-workflows and call the SubFlow state
-as a single state in each.
+<p align="center">
+<img src="media/spec/subflowstateref.png" height="350px" alt="Referencing reusable workflow via SubFlow states"/>
+</p>
+
+Reusable workflow are referenced by their `id` property via the SubFlow states`workflowId` parameter.
+
+Each referenced workflow receives the SubFlow states data as workflow data input.
+
+The `waitForCompletion` property defines if the SubFlow state should wait until the referenced reusable workflow
+has completed its execution. 
 
-Sub-workflows must have a defined start and end states.
-The `waitForCompletion` property defines if the SubFlow state should wait until execution of the sub-workflow
-is completed or not.
+If `waitForCompletion` is "true", SubFlow state execution must wait until the referenced workflow has completed its execution.
+In this case the workflow data output of the referenced workflow can and should be merged with the SubFlow states state data.
 
-Each sub-workflow receives the same copy of the SubFlow state's data input.
-If the `waitForCompletion` property is set to true, sub-workflows have the ability to edit the parent's workflow data.
-If the `waitForCompletion` property is set to false, data access to the parent workflow should not be allowed.
+If `waitForCompletion` is set to "false" the parent workflow can continue its execution while the referenced workflow 
+is being executed. For this case, the referenced (child) workflow data output cannot be merged with the SubFlow states
+state data (as by the time its completion the parent workflow execution has already continued).
 
-Sub-workflows inherit all the [function](#Function-Definition) and [event](#Event-Definition) definitions of their parent workflow.
+Referenced workflows must declare their own [function](#Function-Definition) and [event](#Event-Definition) definitions.
 
 #### Inject State