Documentation review

Hi,

I am reviewing all the docs, and making some improvements, but the branch `feature/generating-docs` doesnt exists anymore, so I am making the pull-request to the `dev` branch.

I will be updating this pull-request as I review the whole documentation.