doc / small refactoring according to feedback