improve documentation

fixes #1391

and add improvements/fixes to documentation
It works. Will replace the current example with this one.