documentation update

orientation documentation

This adds some notes which I think would be important for someone trying to understand how this code gets used.