some reordering of the documentation and trying some more GitHub flavored markdown