Several changes

docs/source/overview.rst

@@ -8,7 +8,7 @@ Workspaces is composed of two major services and a suite of utilities.
 
 Apart from these two, there is also the **notification service**, a shared service for sending notifications.
 
-.. image:: diagrams/overall.png
+.. image:: overview/images/overall.png
    :width: 567px
    :height: 404px
    :alt: diagram showing users and DAs interacting with workspaces UI
@@ -44,11 +44,40 @@ legacy workflow system did not:
     :maxdepth: 2
 
     overview/how-workflows-run-in-the-dsoc-or-naasc.rst
+    overview/workflow-creation.rst
 
 The Capability Service
 ----------------------
 
 The capability service is where most of the interesting complexity comes into play.
+Like the workflow service, the capability service manages the execution of processes.
+However, there are some important distinctions:
+
+* Workflows are *Aristotelian*; they run once and succeed or fail. Capabilities are *Platonic*;
+  many versions of the capability can be executed until the ideal outcome is obtained
+* Workflows are run by machines. Capabilities are run by humans.
+
+You can think of the capability system as the *control system* for Workspaces. The capability service, at its core,
+dispatches behaviors based on events it receives from AMQP. In fact, one of the core design goals of the capability
+system was to be invulnerable to service outages. This works because the capability system is data-driven: the existing
+state is kept in a database, and pending changes of state are persisted by the AMQP system until the capability service
+is able to process them. This is what allows us to weather up to (say) 24 hours of downtime of the entire
+capability and workflow systems.
+
+There are basically three characteristics that differentiate capabilities from
+workflows:
+
+1. Versions. The :doc:`capability version system <overview/capability-versions>` allows users to refine and resubmit
+   requests if the obtained result is unacceptable. This is vital for dealing with iterative processing like calibration
+   and imaging, where due to RFI or instrument failures, new flagging files need to be applied to secure the proper
+   outcome.
+2. States. The :doc:`capability state system <overview/capability-states>` allows us to define arbitrary "workflows" for
+   handling capability requests. These workflows are high-level, like "we must QA before ingesting images," and can
+   include accepting human input and decisions as well as processing.
+3. Queues. The capability queue system allows our stakeholders to specify very high-level constraints on processing,
+   including pausing capability requests altogether, or choosing a number of concurrent requests to permit. This is
+   useful during move configurations when processing should be paused, and then after move configurations to prevent the
+   standard calibration capability from swamping the cluster completely.
 
 .. toctree::
     :maxdepth: 2