improve documentation

fixes #1391

and add improvements/fixes to documentation
I think is `its` not `it's`