updated docs based on discussion in #5