Mostly minor edits

Author: danfunk

doc/bpmn/advanced.rst

@@ -16,7 +16,7 @@ BPMN Tasks have the following additional attributes.
 
 * `bpmn_id`: the ID of the BPMN Task (this will be :code:`None` if the task is not visible on the diagram)
 * `bpmn_name`: the BPMN name of the Task
-* `lame`: the lane of the BPMN Task
+* `lane`: the lane of the BPMN Task
 * `documentation`: the contents of the BPMN `documentation` element for the Task
 * `data_input_associations`: a list of incoming data object references
 * `data_output_associtions`: a list of outgoing data object references
@@ -44,7 +44,7 @@ To retrieve a list of tasks associated with a particular task spec, use :code:`w
 
 .. code:: python
 
-    tasks = workflow.get_tasks_from_spec_name('customize_product')    
+    tasks = workflow.get_tasks_from_spec_name('customize_product')
 
 will return a list containing the Call Actitivities for the customization of a product in our example workflow.
 
@@ -76,7 +76,7 @@ to create a list of all tasks.  It is also possible to start from a particular s
 
 .. code:: python
 
-    tasks = workflow.get_tasks_from_spec_name('customize_prodcut')
+    tasks = workflow.get_tasks_from_spec_name('customize_product')
     subprocess = workflow.get_subprocess(tasks[0])
     subprocess_tasks = workflow.get_tasks(workflow=subprocess)
 
@@ -126,11 +126,11 @@ See the example in :doc:`synthesis` for the basics of creating a parser.  The pa
 
 - a set of namespaces (useful if you have custom extensions)
 - a BPMN Validator (the one in the :code:`bpmn` package validates against the BPMN 2.0 spec)
-- a mapping of XML tag to Task Spec Descriptions.  The default set of descriptions can be found in 
+- a mapping of XML tag to Task Spec Descriptions.  The default set of descriptions can be found in
   :code:`SpiffWorkflow.bpmn.parser.spec_descriptions`.  These values will be added to the Task Spec in the `description` attribute
   and are intended as a user-friendly description of what the task is.
 
-The :code:`BpmnValidator` can be used and extended independently of the parser as well; call :code:`validate` with 
+The :code:`BpmnValidator` can be used and extended independently of the parser as well; call :code:`validate` with
 an :code:`lxml` parsed tree.
 
 Loading BPMN Files
@@ -150,7 +150,7 @@ The following methods are available for discovering the names of processes and D
 - :code:`find_all_spec`: Returns a mapping of name -> :code:`BpmnWorkflowSpec` for all processes used in all files that have been
   provided to the parser at that point.
 - :code:`get_process_dependences`: Returns a list of process IDs referenced by the provided process ID
-- :code:`get_dmn_dependencies`: Returns a list of DMN IDs referenced byt he provided process ID
+- :code:`get_dmn_dependencies`: Returns a list of DMN IDs referenced by the provided process ID
 
 
 Serialization
@@ -171,7 +171,7 @@ Serializing Custom Objects
 In `Custom Script Engines`_ , we add some custom methods and objects to our scripting environment.  We create a simple
 class (a :code:`namedtuple`) that holds the product information for each product.
 
-We'd like to be ble to save and restore our custom object.
+We'd like to be able to save and restore our custom object.
 
 .. code:: python
 
@@ -398,7 +398,7 @@ that this could be a Docker container with a complex environment, an HTTP API ru
 
     Note that our execute method returns :code:`True`.  We could check the status of our process here and return
     :code:`False` to force our task into an `ERROR` state if the task failed to execute.
-    
+
     We could also return :code:`None`
     if the task is not finished; this will cause the task to go into the `STARTED` state.  You would have to manually
     complete a task that has been `STARTED`.  The purpose of the state is to tell SpiffWorkflow your application will
@@ -410,19 +410,14 @@ that this could be a Docker container with a complex environment, an HTTP API ru
 Service Tasks
 -------------
 
-Let's return to the simpler Custom Script Engine case, ignoring the possibility of running in some external environment.
-
-Each of these functions takes a parameter, and if you expect BPMN authors to use them, it's necessary to let them know
-the functions exist, as well as how to call them.  This is a little inconvenient, so an alternative would be to 
-re-implement them as Service Tasks.
-
 Service Tasks are also executed by the workflow's script engine, but through a different method, with the help of some
 custom extensions in the :code:`spiff` package:
 
 - `operation_name`, the name assigned to the service being called
 - `operation_params`, the parameters the operation requires
 
-This is our script engine and scripting enviroment:
+
+This is our script engine and scripting environment:
 
 .. code:: python
 
@@ -449,7 +444,7 @@ This is our script engine and scripting enviroment:
     service_task_engine = ServiceTaskEngine()
 
 Instead of adding our custom functions to the enviroment, we'll override :code:`call_service` and call them directly
-according to the `operation_name` that was given.  The :code:`spiff` Service Task also evaluates the parameters 
+according to the `operation_name` that was given.  The :code:`spiff` Service Task also evaluates the parameters
 against the task data for us, so we can pass those in directly.  The Service Task will also store our result in
 a user-specified variable.
 
@@ -483,8 +478,8 @@ Our `modeler <https://github.com/sartography/bpmn-js-spiffworkflow>`_ has a mean
 their parameters that can be displayed to a BPMN author in the Service Task configurtion panel.  There is an example of
 hard-coding a list of services in
 `app.js <https://github.com/sartography/bpmn-js-spiffworkflow/blob/0a9db509a0e85aa7adecc8301d8fbca9db75ac7c/app/app.js#L47>`_
-and as suggested, it would be reasonably straightforward to replace this with a API call.  SpiffArena has robust
-mechanisms for handling this that might serve as a model for you.
+and as suggested, it would be reasonably straightforward to replace this with a API call.  `SpiffArena <https://www.spiffworkflow.org/posts/articles/get_started/>`_
+has robust mechanisms for handling this that might serve as a model for you.
 
 How this all works is obviously heavily dependent on your application, so we won't go into further detail here, except
 to give you a bare bones starting point for implementing something yourself that meets your own needs.

doc/bpmn/camunda/support.rst

@@ -1,14 +1,23 @@
 Camunda Editor Support
 ======================
 
+.. warning:: There is a better way ...
+  SpiffWorkflow does not aim to support all of Camunda's proprietary extensions.
+  Many of of the items in the Camunda Properties Panel do not work.  And
+  major features of SpiffWorkflow (Messages, Data Objects, Service Tasks, Pre-Scripts, etc...)
+  can not be configured in the Camunda editor.  Use `SpiffArena <https://www.spiffworkflow.org/posts/articles/get_started/>`_
+  to build and test your BPMN models instead!
+
 Earlier users of SpiffWorkflow relied heavily on Camunda's modeler and several of our task spec
 implementations were based on Camunda's extensions.  Support for these extensions has been moved
-to the :code:`camunda` package.  We are not actively maintainin this package (though we will
-accept contriibutions from Camunda users!).
+to the :code:`camunda` package.  We are not actively maintaining this package (though we will
+accept contributions from Camunda users!).  Please be aware that many of the Camunda extensions
+that will appear in the Camunda editor do not work with SpiffWorkflow.
+
 
 .. toctree::
    :maxdepth: 3
 
    tasks
    events
-   multiinstance
+   multiinstance

doc/bpmn/data.rst

@@ -16,7 +16,7 @@ We'll be using the following files from `spiff-example-cli <https://github.com/s
 Data Objects
 ^^^^^^^^^^^^
 
- Data Objects exist at a process level and are not visible in the diagram, but when you create a Data Object
+ Data Objects exist at the process level and are not visible in the diagram, but when you create a Data Object
  Reference, you can choose what Data Object it points to.
 
 .. figure:: figures/data/data_object_configuration.png
@@ -61,17 +61,16 @@ If you have set up our example repository, this model can be run with the follow
 Data Inputs and Outputs
 ^^^^^^^^^^^^^^^^^^^^^^^
 
-In complex workflows, it useful to be able to specify required Data Inputs and Outputs, especially for Call Activities
+In complex workflows, it is useful to be able to specify required Data Inputs and Outputs, especially for Call Activities
 given that they are external and might be shared across many different processes.
 
 When you add a Data Input to a Call Activity, SpiffWorkflow will check that a variable with that name is available to
-be copied into the activity and copy *only* the variables you've specified as inputs.  When you add a Data Output, 
+be copied into the activity and copy *only* the variables you've specified as inputs.  When you add a Data Output,
 SpiffWorkflow will copy *only* the variables you've specified from the Call Activity at the end of the process.  If any
 of the variables are missing, SpiffWorkflow will raise an error.
 
 Our product customization Call Activity does not require any input, but the output of the process is the product
 name and quantity.  We can add corresponding Data Outputs for those.
-
 .. figure:: figures/data/data_output.png
    :scale: 30%
    :align: center

doc/bpmn/events.rst

@@ -220,11 +220,11 @@ In BPMN, Messages are used to communicate across processes.  Technically, Messag
 intended to be used inside a single Process, but Spiff does support this use.
 
 Messages are similar to Signals, in that they are referenced by name, but they have the
-additional property that they may contain a payload.  The payload is a bit of python code that will be 
-evaluated against the task data and sent along with the Message.  In the corresponding Message Catch 
+additional property that they may contain a payload.  The payload is a bit of python code that will be
+evaluated against the task data and sent along with the Message.  In the corresponding Message Catch
 Event or Receive Task, we define a variable name where we'll store the result.
 
-We've added a QA process to our model, which will be initiated whenever an order takes to long
+We've added a QA process to our model, which will be initiated whenever an order takes too long
 to fulfill.  We'll send the reason for the delay in the Message.
 
 Spiff Messages can also optionally use Correlation Keys.  The Correlation Key is an expression or set of
@@ -276,4 +276,4 @@ Running The Model
 .. note::
 
    We're specifying a collaboration rather than a process so that SpiffWorkflow knows that there is more than
-   one top-level process.
+   one top-level process.

doc/bpmn/intro.rst

@@ -3,17 +3,16 @@ BPMN Workflows
 
 The basic idea of SpiffWorkflow is that you can use it to write an interpreter
 in Python that creates business applications from BPMN models.  In this section,
-we'll develop a model of a reasonably complex process and as well as a
-simple workflow runner.
+we'll develop a model of a reasonably complex process and show how to run it.
 
 We expect that readers will fall into two general categories:
 
 - People with a background in BPMN who might not be very familiar Python
 - Python developers who might not know much about BPMN
 
 This section of the documentation provides an example that (hopefully) serves
-the needs of both groups.  We will introduce the BPMN elements that SpiffWorkflow
-supports and show how to build a simple workflow runner around them.
+the needs of both groups.  We will introduce some of the more common BPMN
+elements and show how to build a simple workflow runner around them.
 
 SpiffWorkflow does heavy-lifting such as keeping track of task dependencies and
 states and providing the ability to serialize or deserialize a workflow that
@@ -34,21 +33,21 @@ command:
 
 .. code-block:: console
 
-   ./spiff-bpmn-runner.py -c order_collboration \
+   ./spiff-bpmn-runner.py -c order_collaboration \
         -d bpmn/tutorial/{product_prices,shipping_costs}.dmn \
         -b bpmn/tutorial/{top_level_multi,call_activity_multi}.bpmn
 
+.. sidebar:: BPMN Runner
 
-For a full description of program options:
+  The example app provides a utility for running BPMN Diagrams from the command
+  line that will allow you to introspect a bit on a running process.  You
+  can see the options available by running:
 
-.. code-block:: console
-
-   ./spiff-bpmn-runner.py --help
+     ./spiff-bpmn-runner.py --help
 
 The code in the workflow runner and the models in the bpmn directory of the
 repository will be discussed in the remainder of this tutorial.
 
-The examples have primarily
 
 Supported BPMN Elements
 -----------------------

doc/bpmn/overview.rst

@@ -19,26 +19,30 @@ processes. BPMN links the realms of business and IT, and creates a common proces
 can be shared between the two.
 
 BPMN describes details of process behaviors efficiently in a diagram. The meaning is precise enough
-to describe the technical details that control process execution in an automation engine. 
+to describe the technical details that control process execution in an automation engine.
 SpiffWorkflow allows you to create code to directly execute a BPMN diagram.
 
 When using SpiffWorkflow, a client can manipulate the BPMN diagram and still have their product work
 without a need for you to edit the Python code, improving response and turnaround time.
 
 .. sidebar:: BPMN Modelers
 
-  There are a number of modelers in existence, and any BPMN compliant modeler should work.
-  SpiffWorkflow has some basic support for the free Camunda modeler, in particular, its
-  form building capabilities.
 
-  Our `modeler <https://github.com/sartography/bpmn-js-spiffworkflow>`_ provides several,
-  extensions, including form specifications via JSON Schema.
+  Currently the best way to build BPMN diagrams is through our SpiffArena project
+  which provides a custom BPMN Modeler, along with ways to test and run BPMN diagrams
+  from within a web browser.  Please see our `getting started guide <https://www.spiffworkflow.org/posts/articles/get_started/>`_
+  for more information.
+
+  It is also possible to use version 7 of the Camunda Modeler to create BPMN diagrams.
+  However, be cautious of the properies panel settings, as many of these settings are
+  not a part of the BPMN Standard, and are not handled in the same way within SpiffWorkflow.
+  You can download the Camunda Modeler from `Camunda <https://camunda.com/download/modeler/>`_.
 
 Today, nearly every process modeling tool supports BPMN in some fashion making it a great tool to
-learn and use.  This page provides a brief overview, and the following section provides a more 
+learn and use.  This page provides a brief overview, and the following section provides a more
 in-depth look. There are many resources for additional information about BPMN.
 
-Most of the examples in this guide have been created with 
+Most of the examples in this guide have been created with
 `our modeler <https://github.com/sartography/bpmn-js-spiffworkflow>`_, which is based on
 `bpmn.js <https://bpmn.io/toolkit/bpmn-js/>`_.
 
@@ -83,17 +87,25 @@ the other based on some data condition. BPMN has other gateway types.
 The important point is that we can use a gateway to add a branch in the
 workflow **without** creating an explicit branch in our Python code.
 
-Events
+An Even More Complicated Workflow
 ------
+BPMN is a rich language that can describe many different types of processes. In
+the following pages we'll cover lanes (a way to distribute work across different
+roles) events (a way to handle asynchronous events), multi-instance tasks (that
+can be executed many times in parallel or in sequence) and decomposition (the
+many ways you can interconnect diagrams to build larger more complex processes)
+We are just scratching the surface.  For now let's take one more step and look
+at what Events make possible.
 
+Events
+^^^^^^^
 In the above simple workflows, all of the transitions are deterministic and we
 have direct connections between tasks.  We need to handle the cases where an event
-may or may not happen and link these events in different parts of the workflow or
+may or may not happen, and link these events in different parts of the workflow or
 across different workflows.
 
-BPMN has a comprehensive suite of event elements that can used for this purpose.
-SpiffWorkflow does not support every single BPMN event type, but it can handle
-many of them.
+BPMN has a comprehensive suite of event elements. SpiffWorkflow does not support
+every single BPMN event type, but it can handle many of them.
 
 .. figure:: figures/overview/events.png
    :scale: 25%
@@ -102,7 +114,7 @@ many of them.
    A workflow containing events
 
 
-We've already seen plain Start and End Events.  BPMN also include the concepts
+We've already seen plain Start and End Events.  BPMN also includes the concept
 of Intermediate Events (standalone events that may be Throwing or Catching) as well
 as Boundary Events (which are exclusively Catching).