beginning heruclean task of tidy and improve doco