I moved your post to the top level since this is a sizable topic in itself.
I like these ideas.
@ramey, why does your “should include” have /paper
and the “advocate for” have doc/paper
?
It seems like some Beman libraries will include the source for the paper they implement, but others will not. I like the idea of having a link to the official paper through wg21.link in the top level README.md
as recommended by [README.IMPLEMENTS]. If 99% of users access the paper through that link, I think something like your second suggestion (putting the paper in doc/paper) makes the most sense.
I like the idea of putting examples/
in the top level (as opposed to src/examples
) since it will be immediately obvious for someone looking at the github repository where they can find some example code.