clarifications in the readme and the internal documentation