Docs review

Here are some suggestions on the docs improvement. Overall it's all fine :ok_hand:  I've just added some links, so that you can read the docs jumping from one part to another, plus some minor formatting changes. Also note the `TODO` comments, maybe it's worth to extends a couple of things, but nothing serious is missing :+1: