add more flesh to examples and pitfalls
-rw-r--r-- 227 README.md