diff --git a/README.md b/README.md
index 15426eb..5c24453 100644
--- a/README.md
+++ b/README.md
@@ -3,7 +3,7 @@
 [![CI](https://github.com/PaNOSC-ViNYL/libpyvinyl/actions/workflows/ci.yml/badge.svg)](https://github.com/PaNOSC-ViNYL/libpyvinyl/actions/workflows/ci.yml)
 [![Documentation Status](https://readthedocs.org/projects/libpyvinyl/badge/?version=latest)](https://libpyvinyl.readthedocs.io/en/latest/?badge=latest)
 
-## Summary
+## Overview
 
 The python package `libpyvinyl` exposes the high level API for simulation codes under
 the umbrella of the Virtual Neutron and x-raY Laboratory (ViNYL).
@@ -21,7 +21,7 @@ exposes the interface to
 - Reload a simulation run from disk and continue the run with optionally modified parameters.
 
 The `BaseCalculator` is an abstract base class, it shall not be instantiated as such.
-The anticipated use is to inherit specialised `Calculators` from `BaseCalculator` and to
+The anticipated use is to inherit specialized `Calculators` from `BaseCalculator` and to
 implement the core functionality in the derived class. In particular, this is required
 for the methods responsible to launch a simulation through the `backengine()` method.
 
@@ -32,32 +32,18 @@ and reload the simulation into memory.
 
 ## Problem statement
 Simulating physical processes is a widespread method to investigate *in-silico* complex systems that
-are inaccessible to analytical methods. The "Virtual Neutron and x-raY Laboratory" (ViNYL) 
+are inaccessible to analytical methods. The "Virtual Neutron and x-raY Laboratory" (ViNYL)
 is an attempt to represent essential elements of neutron or x--ray photon beamline experiments through
-software that simulates the radiation passing from the source through beamlines, interacting with a sample and finally being registered in a detection device. In some cases, multipe simulations have be chained in a simulation pipeline, where each segment of the experiment is represented by a different piece
+software that simulates the radiation passing from the source through beamlines, interacting with a sample and finally being registered in a detection device. In some
+cases, multiple simulations have be chained in a simulation pipeline, where each segment of the experiment is represented by a different piece
 of software. Driving such a complex simulation can be an enormous task due to the vast differences 
 with respect to parameter names, unit conventions, configuration syntax, i.e. the user interface. 
 
-The python package `libpyvinyl` provides a way to harmonizes the user interfaces of such simulation codes. It is an object oriented library; its classes define the user interface to simulation codes, simulation parameters, and simulation data. 
+The python package `libpyvinyl` provides a way to harmonize the user interfaces of such simulation codes. It is an object oriented library; its classes define the user interface to simulation codes, simulation parameters, and simulation data.
 
-For a given simulation code, e.g. propagation of neutron or photon beams through a beamline, a new class would have to be defined that derives from the `libpyvinyl` classes and implements the methods
-meant to configure a simulation, launch the simulation code, and retrieve the output data. Since the
-interplay between parametrization, execution, and IO is already taken care of at the level of `libpyvinyl`'s base classes, the effort to define a specialized interface for a new simulation code is rather minimal. This structure allows integrating simulation codes into simulation pipelines in the above sense.
-
-## Overview of base classes
-
-### BaseCalculator
-### CalculatorParameters
-### Parameter
-### BaseData
-### BaseFormat
-### Instrument
-
-## Example
-The subdirectory *test/integration/plusminus* contains a python package that illustrates how a specialized calculator (simulation interface class) can be defined by deriving from the appropriate `libpyvinyl` base classes.
-
-## Real world projects
-TODO
+For a given simulation code, e.g. propagation of neutron or photon beams through a beamline, a new class would have to be defined that derives from the
+`libpyvinyl` classes. Implementing the methods meant to configure a simulation, launch the simulation code, and retrieve the output data. Since the
+interplay between parametrization, execution, and IO is already taken care of at the level of `libpyvinyl`'s base classes, the effort to define a specialized interface (parameters, backengine and DataClass) for a new simulation code is rather minimal. This structure allows integrating simulation codes into simulation pipelines in the above sense.
 
 ## Installation
 
@@ -75,12 +61,12 @@ $> conda create -n libpyvinyl
 $> pip install libpyvinyl
 ```
 
-### Developers
+### Developers of libpyvinyl
 
 We provide a requirements file for developers in _requirements/dev.txt_.
 
 ```
-$> cd requirements  
+$> cd requirements
 ```
 
 ```
@@ -95,7 +81,7 @@ $> pip install -r dev.txt
 
 
 Then, install `libpyvinyl` into the same environment. The `-e` flag links the installed library to
-the source code in the repository, such that changes in the latter are immediately effective in the installed version.
+the source code in the local path, such that changes in the latter are immediately effective in the installed version.
 
 ```
 $> cd ..
@@ -104,7 +90,7 @@ $> pip install -e .
 
 ## Testing
 
-We recommend to run the unittests and integration tests.
+A simple `pytest` command will run the unittests and integration tests.
 ```
 pytest ./
 ```
@@ -141,6 +127,27 @@ Or to run integration tests only:
 pytest tests/integration
 ```
 
+## libpyvinyl projects
+- McStatsScript
+- SimEx-Lite
+
+
+## Overview of base classes
+### BaseCalculator
+The `BaseCalculator` is an abstract base class providing the interface to the computing code: `input` and `output` for the data flow, `CalculatorParameters` to 
+, `backengine` to execute the code. The connection between different `Calculator`s is handled by `BaseData` class.
+### CalculatorParameters
+
+### Parameter
+### BaseData
+### BaseFormat
+### Instrument
+
+## Example
+The subdirectory *test/integration/plusminus* contains a python package that illustrates how a specialized calculator (simulation interface class) can be defined by deriving from the appropriate `libpyvinyl` base classes.
+
+
+
 ## Acknowledgement
 
-This project has received funding from the European Union's Horizon 2020 research and innovation programme under grant agreement No. 823852.
+This project has received funding from the European Union's Horizon 2020 research and innovation programme under grant agreement No. 823852.
\ No newline at end of file