Update doc quickstart (#226)

* Clarify certain points of the quick start, fix typos, add schema

Author: Barthelemy

doc/QuickStart.md

@@ -31,7 +31,7 @@ A Linux machine (CC7 or Ubuntu) or a Mac. See the O2 instructions below for the
 3. Prepare the QualityControl development package
     * `aliBuild init QualityControl@master --defaults o2`
 
-4. Install GLFW to have GUIs in the DPL (optional, DPL GUIs do not work in containers).
+4. Install GLFW to have GUIs in the DPL (optional, DPL GUIs do not work in containers nor over SSH).
     * On CC7 : `sudo yum install glfw-devel --enablerepo=epel`
     * On Mac : `brew install glfw`
 
@@ -52,49 +52,62 @@ To make sure that your system is correctly setup, we are going to run a basic QC
 
 ### Basic workflow
 
-We will run a basic workflow with attached QC described in the following schema.
+We are going to run a basic workflow whose various processes are shown in the following schema. 
 
-![alt text](images/basic-schema.png)
+![basic-schema](images/basic-schema.png)
 
-The _Producer_ is a random data generator. In a more realistic setup it would be a processing device or the _Readout_. The _Data Sampling_ is the system in charge of dispatching data samples from the main data flow to the _QC tasks_. It can be configured to dispatch different proportion or different types of data. The _Checker_ is in charge of evaluating the _MonitorObjects_ produced by the _QC tasks_, for example by checking that the mean is above a certain limit. It can also modify the aspect of the histogram, e.g. by changing the background color or adding a PaveText. Finally the _Checker_ is also in charge of storing the resulting _MonitorObject_ into the repository where it will be accessible by the web GUI. It also pushes it to a _Printer_ for the sake of this tutorial.
+The _Producer_ is a random data generator. In a more realistic setup it would be a processing device or the _Readout_. The _Data Sampling_ is the system in charge of dispatching data samples from the main data flow to the _QC tasks_. It can be configured to dispatch different proportion or different types of data. The __tasks__ are in charge of analyzing the data and preparing QC objects, often histograms, that are then pushed forward every cycle. A cycle is 10 second in this example. In production it is closer to 1 minute. The _Checker_ is in charge of evaluating the _MonitorObjects_ produced by the _QC tasks_. It runs _Checks_ defined by the users, for example checking that the mean is above a certain limit. It can also modify the aspect of the histogram, e.g. by changing the background color or adding a PaveText. Finally the _Checker_ is also in charge of storing the resulting _MonitorObject_ into the repository where it will be accessible by the web GUI. It also pushes it to a _Printer_ for the sake of this tutorial.
 
 To run it simply do:
 
     o2-qc-run-basic
 
 Thanks to the Data Processing Layer (DPL, more details later) it is a single process that steers all the _devices_, i.e. processes making up the workflow. A window should appear that shows a graphical representation of the workflow. The output of any of the processes is available by double clicking a box. If a box is red it means that the process has stopped, probably abnormally.
 
-![alt text](images/basic-dpl-gui.png)
+![basic-dpl-gui](images/basic-dpl-gui.png)
 
-The presented example consists of one DPL workflow which has both the main processing and QC infrastructure declared inside. In the real case, we would usually prefer to attach the QC without modifying the original topology. It can be done by merging two (or more) workflows, as below:
+The example above consists of one DPL workflow which has both the main processing and the QC infrastructure declared inside. In the real case, we would usually prefer to attach the QC without modifying the original topology. It can be done by merging two (or more) workflows, as shown below:
 
     o2-qc-run-producer | o2-qc --config json://${QUALITYCONTROL_ROOT}/etc/basic.json
 
-This command uses two executables. The first one contains the _Producer, which represents a main data flow. The second executable generates the QC infrastructure based on given configuration file. These two workflows are joined together using the pipe | character. This example illustrates how to add QC to any DPL workflow by using `o2-qc` and passing it a configuration file. 
+![basic-schema-2-exe](images/basic-schema-2-exe.png)
+
+This command uses two executables. The first one contains only the _Producer (see Figure above), which represents the data flow to which we want to apply the QC. The second executable generates the QC infrastructure based on the given configuration file (more details in a few sections). These two workflows are joined together using the pipe `|` character. This example illustrates how to add QC to any DPL workflow by using `o2-qc-run-qc` and passing it a configuration file. 
 
 __Repository and GUI__
 
 The data is stored in the [ccdb-test](ccdb-test.cern.ch:8080/browse) at CERN. If everything works fine you should see the objects being published in the QC web GUI (QCG) at this address : [https://qcg-test.cern.ch/?page=objectTree](https://qcg-test.cern.ch/?page=objectTree). The link brings you to the hierarchy of objects (see screenshot below). Open "QcTask" (the task you are running) and click on "example" which is the name of your histogram. The plot should be displayed on the right. If you wait a bit and hit "REFRESH NOW" in the far left menu you should see it changing from time to time (see second screenshot below). 
-Please note that anyone running o2-qc-run-basic publishes the same object and you might see the one published by someone else. 
+Please note that anyone running o2-qc-run-basic publishes the object under the same name and you might see the one published by someone else. 
 
 ![alt text](images/basic-qcg1.png)
 ![alt text](images/basic-qcg2.png)
 
-TODO add a link to the user documentation of the QCG
+TODO add a link to the user documentation of the QCG when it is written.
 
 __Configuration file__
 
-The devices are configured in the config file named `basic.json`. It is installed in `$QUALITYCONTROL_ROOT/etc`. Each time you rebuild the code, `$QUALITYCONTROL_ROOT/etc/basic.json` is overwritten by the file in the source directory (`~/alice/QualityControl/Framework/basic.json`).
+In the example above, the devices are configured in the config file named `basic.json`. It is installed in `$QUALITYCONTROL_ROOT/etc`. Each time you rebuild the code, `$QUALITYCONTROL_ROOT/etc/basic.json` is overwritten by the file in the source directory (`~/alice/QualityControl/Framework/basic.json`).
+
+The configuration for the QC is made of many parameters described in an [advanced section of the documentation](https://github.com/AliceO2Group/QualityControl/blob/master/doc/Advanced.md#configuration-files-details). For now we can just see below the definition of a task. `moduleName` and `className` specify respectively the library and the class to load and instantiate to do the actual job of the task. 
+```json
+(...)
+"tasks": {
+  "QcTask": {
+    "active": "true",
+    "className": "o2::quality_control_modules::skeleton::SkeletonTask",
+    "moduleName": "QcSkeleton",
+    "cycleDurationSeconds": "10",
+(...)
+```
+Try and change the name of the task by replace `QcTask` by a name of your choice. Relaunch the workflows. You should now see the object published under a different directory in the QCG.
 
 ### Readout chain
 
-In this second example, we are going to use the Readout as data source.
+In this second example, we are going to use the Readout as our data source.
 
 ![alt text](images/readout-schema.png)
 
-This workflow is a bit different from the basic one. The _Readout_ is not a device and thus we have to have a _proxy_ to get data from it. This is the extra box going to the _Dispatcher_, which then injects data to the task. This is handled in the _Readout_ if you enable the corresponding configuration flag.
-
-TODO make the qc task use the daq code
+This workflow is a bit different from the basic one. The _Readout_ is not a DPL, nor a FairMQ, device and thus we have to have a _proxy_ to get data from it. This is the extra box going to the _Data Sampling_, which then injects data to the task. This is handled in the _Readout_ as long as you enable the corresponding configuration flag.
 
 To do so, open the readout config file located at `$READOUT_ROOT/etc/readout.cfg` and make sure that the following properties are correct :
 
@@ -116,7 +129,7 @@ Start Readout :
 readout.exe file://$READOUT_ROOT/etc/readout.cfg
 ```
 
-Start the proxy, DS (DataSampling) and QC workflows :
+Start the proxy, DataSampling and QC workflows :
 ```
 o2-qc-run-readout | o2-qc --config json://${QUALITYCONTROL_ROOT}/etc/readout.json
 ```
@@ -138,7 +151,7 @@ equipment-player-* 	fillPage 	int 	1 	If 1, content of data file is copied multi
 
 #### Readout data format as received by the Task
 
-The header is a O2 header populated with data from the header built by the Readout. 
+The header is an O2 header populated with data from the header built by the Readout. 
 The payload received is a 2MB (configurable) data page made of CRU pages (8kB).
 
 __Configuration file__