lots of work on the docs

Signed-off-by: Ian Bell <ian.h.bell@gmail.com>