Docs improvements

Some docs improvements solving some issues.
Yes. But this pull request is too large. What you think I send a new pull request to fix all indentation in docs?