document more defaults and improve wording a bit