incremental update - refactorings + documentation