rejig documentation slightly