refactored the documentation to bring it to a "reasonable" level