Docs: Run Output - Clarification and Additions

Clarification of the meanings of and the distinction between the
output-related terms iteration, job, workload and section for those
unfamiliar
- Add entries to the glossary and references to the glossary
- Added section on Configuration parameter hierarchy
- Added section on the number and names of directories generated for
jobs in the run output folder

doc/source/user_information/user_reference/agenda.rst

@@ -59,7 +59,7 @@ An example agenda can be seen here:
                 num_big_cores: 4
                 num_little_cores: 0
 
-    workloads:                  # List which workloads should be ran
+    workloads:                  # List which workloads should be run
     -   name: benchmarkpi
         augmentations:
             - ~trace-cmd        # Disable the trace-cmd instrument for this workload
@@ -160,15 +160,15 @@ Plugins
 workloads
 ^^^^^^^^^
 
-Here you can specify a list of workloads to be ran. If you wish to run a
+Here you can specify a list of workloads to be run. If you wish to run a
 workload with all default values then you can specify the workload name directly
 as an entry, otherwise a dict mapping should be provided. Any settings provided
 here will be the most specific and therefore override any other more generalised
 configuration for that particular workload spec. The valid entries are as
 follows:
 
-:workload_name: **(Mandatory)** The name of the workload to be ran
-:iterations: Specify how many iterations the workload should be ran
+:workload_name: **(Mandatory)** The name of the workload to be run
+:iterations: Specify how many iterations the workload should be run
 :label: Similar to IDs but do not have the uniqueness restriction.
     If specified, labels will be used by some output processors instead of (or in
     addition to) the workload name. For example, the csv output processor will put

doc/source/user_information/user_reference/configuration.rst

@@ -21,7 +21,9 @@ if it does not already exist. This file must always exist and will always be
 loaded. You can add to or override the contents of that file on invocation of
 Workload Automation by specifying an additional configuration file using
 ``--config`` option. Variables with specific names  will be picked up by the
-framework and used to modify the behaviour of Workload automation.
+framework and used to modify the behaviour of Workload automation e.g.
+the ``iterations`` variable might be specified to tell WA how many times to run
+each workload.
 
 ---------------------
 
@@ -97,3 +99,9 @@ it is not possible to know the end users intention and WA will error.
 This functionality allows for defaults for plugins, targets etc. to be
 configured at a global level and then seamless overridden without the need to
 remove the high level configuration.
+
+Dependent on specificity, configuration parameters from different sources will
+have different inherent priorities. Within an agenda, the configuration in
+"workload" entries wil be more specific than "sections" entries, which in turn
+are more specific than parameters in the "config" entry.
+

doc/source/user_information/user_reference/output_directory.rst

@@ -43,6 +43,11 @@ iterations each of ``dhrystone`` and ``memcpy`` workloads with no augmentations
 enabled, and with the first attempt at the first iteration of dhrystone having
 failed.
 
+You may notice that a number of directories named ``wk*-x-x`` were generated in the
+output directory structure. Each of these directories represents a
+:term:`job`. The name of the output directory is as stated :ref:`here <job_execution_subd>`.
+
+
 Output Directory Entries
 ------------------------
 
@@ -81,6 +86,7 @@ __failed
         failed and were re-run. This directory contains output directories for
         the failed attempts.
 
+.. _job_execution_subd:
 job execution output subdirectory
         Each subdirectory will be named ``<job id>_<workload label>_<iteration
         number>``, and will, at minimum, contain a ``result.json`` (see above).