I think I know where this 'best practice' concept comes from, but its an ancient thing that was thrown around that keeps propagating itself in PL :-). I've always put them under 'examples' instead to reflect what they truly are. In a way though, one would argue that examples are best kept in the README.pp so one can add context. My main concerns are that they are a secondary place to update that is more often then not forgotten. But alas, this is a different discussion :-).