better way to document "state" choices