Feature/update readme

@brutski @jlo188 Please review and merge.

I have updated the documentation and ad hoc'd it. There is one broken link pending a documentation PR in crichton. Otherwise, should all be good.