(PDOC-13) Update README with examples and resources

In order to make it easier for users, give some basic examples
in the README of how write documentation that is compatible with
strings. Also provide a few resources for getting started.
"plan to move away from RDoc and instead use Markdown."

(I think it is better to be more prescriptive - i.e do try it out with RDoc, but the standard is planned to be Markdown).