comments from Mikhail

docs/source/tutorial.rst

@@ -3,6 +3,8 @@
 Tutorial
 ========
 
+The goal of this tutorial is to demonstrate the functionality of the offline calibration tool-chain. The main functionality offered by this package is the possibility to run a notebook on the shell with input parameters for the configuration. Extending that concept the package also takes care of starting the necessary jobs on the maxwell cluster, which can be more than one if the notebook makes use of ipyparallel. Finally the pycalibration package will generate a report containing all markup and result cells of the notebook.
+
 The Tutorial consist of this documentation and two very simple notebooks:
 
 1. notebooks/Tutorial/startversion.ipynb
@@ -12,11 +14,28 @@ The Tutorial consist of this documentation and two very simple notebooks:
 2. notebooks/Tutorial/calversion.ipynb
 
    Outcome of adapting the startversion notebook to be able to be run with the offline
-   calibtaion tool-chain.
+   calibration tool-chain.
+
+To have a look at those notebooks start from a shell with the karabo environment::
+  
+  jupyter-notebook
+
+This will open a jupyter kernel running in your browser where you can then open the notebooks in the folder notebooks/Tutorial. If you in addition also start on another shell the ipcluster as instructed in the calversion.ipynb notebook::
+
+  ipcluster start --n=4 --profile=tutorial
+
+you can step through the cells and run them.
+If you run this notebook using the xfel-calibrate command as explaind at the end of this tutorial you do not need to start the cluster yourself, it will be done by the framework.
+
 
 Installation and Configuration
 ------------------------------
 
+The offline calibration tool-chain is optimised to run on the maxwell cluster.
+For more information refer to the Maxwell_ documentation.
+
+.. _Maxwell: https://confluence.desy.de/display/IS/Running+Jobs+on+Maxwell
+
 In order to use the offline calibration tool a few steps need to be carried out
 to install the necessary packages and setup the environment:
 
@@ -69,4 +88,9 @@ Running the notebook
 
      xfel-calibrate Tutorial TEST
 
-3. Look at generated report in the chosen output folder.
+   You can see your job in the queue with::
+
+     squeue -u username
+
+3. Look at the generated report in the chosen output folder.
+4. More information on the job run on the cluster can be found in the temp folder.

xfel_calibrate/notebooks.py

@@ -86,7 +86,7 @@ notebooks = {
                                "notebook": "notebooks/Tutorial/calversion.ipynb",
                                "concurrency": {"parameter": None,
                                                "default concurrency": None,
-                                               "cluster cores": 4},
+                                               "cluster cores": 32},
                                },
                       }