additional copy and markdown tweaks

I've added a little more context for first time readers and changed from HTML to markdown where I can.

I wanted to link to the docs/examples directory but can't see how

/cc @snehaso