Doc update

This is related to issue #1474

I know that this branch is not really ready to be merged but I still open this to get advise and feedback on the update.

I didn't generate the PDF but I can do it if you prefer reading PDF files.