update the docs on data

docs/Building_Diagrams/data.md

@@ -0,0 +1,9 @@
+# Data
+
+```{toctree}
+:maxdepth: 1
+:caption: Types of Data
+task_data.md
+data_objects.md
+data_stores.md
+```

docs/Building_Diagrams/data_objects.md

@@ -35,12 +35,6 @@ Signifies the data or information that is generated or produced as a result of e
 
 A Data Object in BPMN typically represents a specific piece of information or a data entity that is exchanged or manipulated during the course of a business process. It can represent both physical and digital data. Examples of Data Objects include documents, forms, reports, databases, or any other data entity relevant to the process. 
 
-### Data Store
-
-![data_store](images/data_store.png) 
-
-A Data Store represents a persistent storage location where data is stored and retrieved during the course of a process. It typically represents a database, file system, or any other storage mechanism. Data Stores are used to depict the long-term storage of data that can be accessed by multiple activities or tasks within the process. They provide a centralized location for data storage and retrieval.
-
 ## Data Input Configuration
 
 | 💻 Form | ⌨ Field Input | 📝 Description |

docs/Building_Diagrams/data_stores.md

@@ -0,0 +1,12 @@
+# Data Stores
+
+![data_store](images/data_store.png) 
+
+A Data Store is a BPMN construct that represents a storage location where data is stored and retrieved and can be accessed among multiple process instances, including for different process models.
+It can represent a database, file system, or any other storage mechanism.
+
+## When to use
+
+You might use a Data Store when you it is not sufficient for data to be accessible in just a single process instance, but it needs to be shared across process instances.
+If you a have a use case where you need to store data and access it from multiple different process instances, you could also consider using a Service Task to contact a database external to SpiffWorkflow, either via a database library in a connector or using a database via API.
+All of these mechanisms work well in SpiffWorkflow, so the choice will depend on your storage and performance requirements.

docs/Building_Diagrams/task_data.md

@@ -0,0 +1,17 @@
+# Task Data
+
+Task data is copied from task to task.
+
+For example, consider the following sequence of tasks:
+
+1. Start Event
+2. Set Variable (sets variable a)
+3. Read Variable (reads variable a)
+
+In this scenario, if the "Set Variable" task sets the value of variable a to the number 1, the "Read Variable" task that follows can access that value (oh, cool, 1).
+
+When the flow splits, as in a set of parallel branches, each branch gets a copy of the same data.
+Then, when the data is merged back together at a merging gateway, if multiple branches write to the same variable, the last branch to complete will be the data that is propagated to tasks after the merging gateway.
+Therefore, if you have tasks a, b, and c that run in parallel, it might not be a good idea for both a and b to set the "desired_withdrawal_amount" variable, since, depending on how fast a and b ran (and other implementation details around the parallel processing), the expected "winner" would not be knowable in advance.
+
+This general branching and merging strategy is applied to all parallel constructs, including inclusive gateways.

docs/index.md

@@ -20,7 +20,7 @@ Building_Diagrams/signal_events.md
 Building_Diagrams/Displaying_Content.md
 Building_Diagrams/Script_Tasks.md
 Building_Diagrams/sub-processes_and_call_activities.md
-Building_Diagrams/data_objects.md
+Building_Diagrams/data.md
 Building_Diagrams/dmn.md
 Building_Diagrams/Extensions.md
 Building_Diagrams/pools_and_lanes.md