improved documentation

/cc @aheusingfeld