read me extended with useful notes