(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.
"a few different comment formats can be used" (easier to read, I read it as "compatible YARD" since I expected it to continue with what is compatible with).