document future improvements & refactoring