Some updates

docs/conf.py

@@ -22,8 +22,6 @@
 templates_path = ['_templates']
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
-
-
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 

docs/guide/intro.rst

@@ -6,7 +6,7 @@ Tasks form a directed acyclic graph (DAG)
 
 Any large-scale campaign can be described as a directed acyclic graph of
 tasks, where edges represent the flow of information from an earlier stage
-to a later stage. This graph is directed because the outputs of one dask can
+to a later stage. This graph is directed because the outputs of one task can
 be the inputs of a future task, and it is acyclic because it is not possible
 for a task to require its own outputs as an input.
 
@@ -16,40 +16,58 @@ executing these task graphs.
 Three databases in Exorcist
 ---------------------------
 
-The basic idea of Exorcist is that to separate three types of data storage:
+The central idea of Exorcist is to separate three types of data storage:
 
 * **Task Status Database**: The task status database is the core of
-  Exorcist, and fully implemented in Exorcist
+  Exorcist, and fully implemented in Exorcist. This database contains the
+  task identifiers, and information on the execution status of those tasks.
+  It is intentionally small and simple, to enable better concurrency.
 * **Task Details Database**: The task details database is a key-value store
   that describes the tasks to be performed; this is specific to the
-  application
+  client application. The client must define how these tasks are serialized
+  and deserialized into the database.
 * **Results Store**: The results store is a generic storage of result data
   from the specific application. The only thing Exorcist needs to know is
-  whether the received result was a success or a failure (in which case, it
-  can be retried).
+  whether the received result was a success or a failure (in which case,
+  Exorcist can take responsibility for ensuring that it gets retried).
 
 Some aspects that distinguish Exorcist from similar tools are the separation
 of task status from task descriptions, and the ability for the user to
 customize how task descriptions or task status are stored.
 
-Practical usage
----------------
+Practical usage for users
+-------------------------
 
-In practice, we tend to think of the user's experience in two stages:
-planning the initial campaign, and the running the campaign. 
+When thinking about the end user's experience, Exorcist tends to assume that
+this occurs in two stages: planning the initial campaign, and the running
+the campaign. The general assumption is that these will beqtwo different
+software tools (typically two executables) with different user experiences.
 
-Planning the campaign
-~~~~~~~~~~~~~~~~~~~~~
+Preparing the campaign: the planner
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 For many use cases, planning the campaign happens on the user's workstation
-or on the head node of a cluster. While this can, in principle, be an
-expensive stage, which runs on a compute node, it is more frequently
-something that is done interactively by the user.
+or on the head node of a cluster. While this can, in principle, be a stage
+that must run on a compute node, it is more frequently something that is
+done interactively by the user.
+
+The "campaign planner" tool must have write access to the *task status
+database* and to the *task details database*.
 
-The "campaign planner" tool must have write access to the task status
-database and to the task details database.
 
 Running a campaign: the worker
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The second 
+The second tool that the user interacts with is the worker. Typically, the
+user will launch many identical workers through jobs submitted to their
+queueing system.
+
+The worker is the workhorse of the campaign. It does the real computational
+effort. It needs read/write access to the *task status database*, read access
+to the *task details database*, and write access to the *results store*.
+
+In most cases, it will also have read access to the results store, which
+allows things like analysis as a separate task. If it can also have write
+access to the the task details database, this allows on-the-fly creation of
+new tasks, e.g., focusing simulation effort in a different direction based
+on the results of the campaign so far.

docs/index.rst

@@ -1,15 +1,20 @@
 Exorcist
 ========
 
-Exorcist is a tool for execution and orchestration of many-task computing.
-It is specifically designed for a common case in the field of simulation,
-where a large simulation campaign may include many loosely coupled
-individual simulations, each of which may requires hours to days to run, and
-the results need to be gathered into a large storage backend.
+*Task execution/orchestration, without the daemons*
+
+Exorcist is a tool for execution and orchestration of many-task
+computing/high-throughput computing.  It is specifically designed for a
+common case in the world of simulation, where a large simulation campaign
+may include many loosely coupled individual simulations, each of which may
+require hours to days to run, and the results need to be gathered into a
+large storage backend.
 
 At small to moderate scale, Exorcist can run without setting up any
 long-running daemon. At larger scales, Exorcist can interface with standard
-database backends, e.g. PostgreSQL.
+database backends, e.g. PostgreSQL. In this way, Exorcist offers the easy
+set-up procedure of a daemonless solution, while offering a smooth
+transition to a highly scalable solution when needed.
 
 .. toctree::
    :maxdepth: 2