doc: Partially incorporated comments form Loic Dachary and Aaron Ten Clay.

Signed-off-by: John Wilkins <john.wilkins@inktank.com>