updates to best practices and gotchas