diff --git a/README.md b/README.md
index 9e0b3b41643522a311d5eab8450e7b337a2f31cb..61272b4c990bfda4d6641fc759517b4189c5fc47 100644
--- a/README.md
+++ b/README.md
@@ -1,18 +1,24 @@
 # DART-WRF
 
-This code runs an Ensemble Data Assimilation system with the software packages DART and WRF. All workflow steps are submitted to the cluster manager SLURM, which takes care of the dependencies.
+This code runs an Ensemble Data Assimilation system with the software packages DART and WRF. All workflow steps are submitted to the cluster manager SLURM, which takes care of the dependencies (the order in which tasks are done).
 
 - Why should I use it?
   - It's pythonic: see what it does at first glance, modular, flexible
   - It handles dependencies using SLURM without '`sleep` loops in the bash script'. 
 Functions return a SLURM ID which can be used to trigger the start of another function (interface by [brentp/slurmpy](https://github.com/brentp/slurmpy)).
 
+- How does it work?
+  - There are two kinds of code/scripts: One that is run immediately and one that is run later on.
+  - The first one instructs the cluster (SLURM) to do the things you tell it - in the right order - using the right input. Example: [`scheduler.py`](https://github.com/lkugler/DART-WRF/blob/master/scheduler.py)
+  - The latter kind of code actually does the things. It is not run right away, but when SLURM says "it's your turn now" - which depends on the available resources on the shared cluster. Example: [prepare_nature.py](https://github.com/lkugler/DART-WRF/blob/master/scripts/prepare_nature.py) and other files in the `/scripts` folder.
+
 - Can I use it for real weather?
-  -  Yes, but you need to [convert your observations into DART format.](https://dart.ucar.edu/pages/Observations.html#obs_real)
+  -  Yes, but you need to [convert your observations into DART format.](https://docs.dart.ucar.edu)
 
 ### A possible workflow:
-`scheduler.py`
+[`scheduler.py`](https://github.com/lkugler/DART-WRF/blob/master/scheduler.py) 
 ```python
+### define your functions gen_synth_obs, assimilate, run_ENS, ...
 
 # create initial conditions
 id = prep_osse()  
@@ -69,9 +75,11 @@ $ squeue -u `whoami` --sort=i
       308393_[1-5]  mem_0384 EnsWRF-3  lkugler PD       0:00      1 (Dependency)
 ```
 
-### Easily switch between clusters
+### Configure your experiment
+Define simulation specific variables in [`config/cfg.py`](https://github.com/lkugler/DART-WRF/blob/master/config/cfg.py).
 
-`config/clusters.py `
+### Easily switch between clusters
+Define cluster specific variables in `config/clusters.py `:
 ```python
 
 clusterA = ClusterConfig()
@@ -83,16 +91,10 @@ clusterB.name = 'jet'
 clusterB.userdir = '/home/pathB/myuser/'
 ```
 
-`config/cfg.py`
-```python
-
-from . import clusters
-cluster = clusters.clusterA  # change cluster configuration here
-```
-
 
 ### References
 This workflow was created following the [DART-WRF Tutorial](http://www.image.ucar.edu/wrfdart/tutorial/).
+Read the DART documentation: [docs.dart.ucar.edu](https://docs.dart.ucar.edu)
 DART is available at github: [@NCAR/DART](https://github.com/NCAR/DART)
 
 ### License