revise the sections and text

Author: SarahAlidoost

_episodes/06-debugging.md

@@ -7,7 +7,7 @@ questions:
 objectives:
 - "Fix a broken recipe"
 keypoints:
-- "The log files contain information about errors and warnings."
+- "There are two different kinds of log files: ``main_log.txt``, and ``main_log_debug.txt``."
 ---
 
 Every user encounters errors. Once you know why you get certain types of errors,
@@ -20,10 +20,10 @@ This lesson helps to understand what the different types of errors are and when
 
 Each time we run ESMValTool, it will produce a new output directory.
 This directory should contain the ``run`` folder that is automatically generated by ESMValTool.
-To examine this, we run an example recipe that can be found in:
-[recipe_example.yml](link).
+To examine this, we run a ``recipe_example.yml`` that can be found in
+[Setup]({{ page.root }}{% link setup.md %}).
 Let's download it to our working directory ``esmvaltool_tutorial`` that was created during
-the [Setup]({{ page.root }}{% link setup.md %}).
+the [Configuration]({{ page.root }}{% link _episodes/03-configuration.md %}).
 
 In a new terminal, go to our working directory ``esmvaltool_tutorial`` where
 both files ``user-config.yml`` and ``recipe_example.yml`` are located and run the recipe:
@@ -154,14 +154,11 @@ and then <kbd>ctrl</kbd> + <kbd>X</kbd> to exit ``nano``.
 >~~~
 {: .solution}
 
-We change the ``projects`` value ``ukesm`` to ``tutorial``:
+## Keys and values in recipe settings
 
-~~~YAML
-19      projects:
-20        - tutorial
-~~~
-
-Also, let's add the preprocessor ``extract_region`` to the section ``prep_timeseries``:
+The [ESMValTool pre-processors](https://docs.esmvaltool.org/projects/ESMValCore/en/latest/recipe/preprocessor.html?highlight=preprocessor) cover a broad range of operations on the input data,
+like time manipulation, area manipulation, land-sea masking, variable derivation, ... .
+Let's add the preprocessor ``extract_region`` to the section ``prep_timeseries``:
 
 ~~~YAML
 25    preprocessors:
@@ -175,6 +172,13 @@ Also, let's add the preprocessor ``extract_region`` to the section ``prep_timese
 33          end_latitude: 70
 ~~~
 
+Also, we change the ``projects`` value ``ukesm`` to ``tutorial``:
+
+~~~YAML
+19      projects:
+20        - tutorial
+~~~
+
 Then, we save the file and run the recipe:
 ~~~bash
   esmvaltool -c user-config.yml recipe_example.yml
@@ -188,13 +192,12 @@ attach the run/recipe_*.yml and run/main_log_debug.txt files from the output dir
 ~~~
 {: .error}
 
-The values for the keys ``author``, ``maintainer``, ``projects`` and ``references`` in the recipe should be known by ESMValTool.
-
-> ## ESMValTool pre-processors
->
-> The [ESMValTool pre-processors](https://docs.esmvaltool.org/projects/ESMValCore/en/latest/recipe/preprocessor.html?highlight=preprocessor) cover a broad range of operations on the input data,
-like time manipulation, area manipulation, land-sea masking, variable derivation, ... .
-{: .callout}
+The values for the keys ``author``, ``maintainer``, ``projects`` and ``references`` in the recipe should
+be known by ESMValTool. A list of ESMValTool author, maintainer, references, and projects can be found
+in the ``config-references.yml`` that is located in the folder ``references``
+in the ESMValTool installation directory ``path_to_esmvaltool``. To find ``path_to_esmvaltool``
+on your system, see
+[Installation]({{ page.root }}{% link _episodes/02-installation.md %}).
 
 > ## ESMValTool can’t locate the data
 >
@@ -218,13 +221,20 @@ What suggestions would you give the researcher for fixing the error?
 > {: .solution}
 {: .challenge}
 
-> ## Check pre-processed data
+## Check pre-processed data
+
+The setting ``save_intermediary_cubes`` in the configuration file can be used
+to save the pre-processed data. More information about this setting can be found at
+[Configuration]({{ page.root }}{% link _episodes/03-configuration.md %}).
+
+> ## save_intermediary_cubes
 >
-> The setting ``save_intermediary_cubes`` in the configuration file can be used
-save the pre-processed data. More information about this setting can be found at
-[Configuration]({{ page.root }}{% link _episodes/03-configuration.md %})
+> Note that this setting should be only used for debugging, as it significantly slows down the recipe
+and increases disk usage because a lot of output files need to be stored.
 {: .callout}
 
+## Check diagnostic script path
+
 The result of the pre-processor is passed to the ``diagnostic_timeseries.py`` script,
 that is introduced in the recipe as: