document organisation and fix ups