Docs for usersctips and payu stages (#489)

Add details on how userscripts work and the payu stages
---------

Co-authored-by: Aidan Heerdegen <[email protected]>

docs/source/config.rst

@@ -341,24 +341,21 @@ FMS based model only options:
    is then ``ncpus / nthreads``
 
 
-Postprocessing
+User Processing
 --------------
 
-``collate`` (*Default:* ``True``)
-   Controls whether or not a collation job is submitted after model execution.
-
-   This is typically ``True``, although individual model drivers will often set
-   the default value to ``False`` if collation is unnecessary.
-
-   See above for specific ``collate`` options.
-
 ``userscripts``
-   Namelist to include separate userscripts or subcommands at various stages of
+   Configure userscripts or subcommands to run at various :ref:`stages<experiment-steps>` of
    a payu submission. Inputs can be either script names (``some_script.sh``) or
    individual subcommands (``echo "some_data" > input.nml``, ``qsub
-   some_script.sh``).
+   some_script.sh``). Userscripts are run within the same PBS job as the model 
+   execution unless the script starts a new PBS job. Userscripts therefore have
+   the same compute, storage and network access as the model. The exceptions to 
+   this are when ``payu setup`` is called directly, then the relevant userscripts 
+   will run on the login node, and the ``sync`` userscript, which runs in the 
+   ``sync`` job.
 
-   Specific scripts are defined below:
+   Specific stages are defined below:
 
    ``init``
       User-defined command to be called after experiment initialization, but
@@ -381,9 +378,10 @@ Postprocessing
       returns an error code. Useful for automatic error postmortem.
 
    ``sync``
-      User-defined command to be called at the start of the ``sync`` pbs job.
-      This is useful for any post-processing before syncing files to a remote
-      archive.
+      User-defined command to be called at the start of the ``sync`` PBS job. 
+      This is useful for any post-processing before syncing files to a remote 
+      archive. Note these scripts are only run if automatic syncing is enabled 
+      or if payu sync is run manually.
 
 ``postscript``
    This is an older, less user-friendly, method to submit a script after ``payu`` 

docs/source/design.rst

@@ -47,6 +47,27 @@ Work Path
    Experiments that are actively running are stored in the work path. For an
    experiment named ``myrun``, the default directory is ``${LAB}/work/myrun``.
 
+.. _experiment-steps:
+Experiment Steps
+================
+
+Payu runs through several steps to setup, run and clean-up an experiment, outlined below:
+
+init
+   Experiment initialization runs first, and includes reading in configuration information and updating the metadata.
+
+setup
+   Setup creates the ephemeral work directory and updates manifests. It is what is run with the ``payu setup`` command. 
+
+run
+   This is the step which does any automated ``runlog`` commands (``git commit``) and executes the model.
+
+error
+   The error stage is entered if the model runs but returns an error code.
+
+archive
+   If the model run is succesful, payu archives the results from the work directory to the output directories.
+
 
 Style Guide
 ===========