better document (and fix) settings