first update of documentation. still incomplete