improved docs

Signed-off-by: Tim Henderson <tim.tadh@gmail.com>