Address Zooko's comments on documentation for #1732.

Signed-off-by: Daira Hopwood <david-sarah@jacaranda.org>