improve documentation

fixes #1391

and add improvements/fixes to documentation
for a quick start I would import the specific functions I need... the `*` import, in my opinion, is not the best choice for an introductory view...