docs: updates as part of review

Some small changes as a result of review comments from Stefan and Jack.

Signed-off-by: Richard Case <[email protected]>

Author: richardcase