update documentation so we can remember how to author