improve documentation

fixes #1391

and add improvements/fixes to documentation
`user` can be avoided here... I think...