Document some gotchas

This pull request contains some document updates for some gotchas I ran into.