documentation of new refactoring for my understanding