(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.
here I would expect a tag - if you are uncomfortable including @see then skip this as it makes you wonder how to do that and references to other documents.