updated docs after discussion with brad