improve documentation

fixes #1391

and add improvements/fixes to documentation
First, as English is not my mother langue, maybe my comments are biased or invalid...
Well this first paragraph seems to me a veryyyy large sentence and easy to get lost. Probably is better to split the ideas inside one paragraph but in several sentences.