Revised documentation based on feedback from @jsuereth