improved documentation (in progress)