improve documentation (to address #2)