minor improvements to docs and examples