document some gotchas and solutions