Also fix some comments that didn't fit onto one line in the yaml examples, be consistent about putting a blank line above `---` yaml separators, and some other small doc improvements.
Signed-off-by: Monis Khan <mok@vmware.com>