This is great advice and I wish it was the standard. I had this problem on one of my projects so I used a githook to basically paste in actual compiled example

This is great advice and I wish it was the standard. I had this problem on one of my projects so I used a githook to basically paste in actual compiled example files from the test suite on committing. It does mean the actual readme is more like a template and you can't edit the README file directly anymore but all the examples always work now! I personally like at least one small example embedded in the README since it's zero effort, an example folder is great for _more_, but annoying to get started, what should I look at in the example folder first?