improved documentation based on feedback from Thomas Knight