document important gotcha