A few notes in the documentation.

This depends on #18, so the PR is against the `utils` branch. Change to be against master, once #18 is merged.

Small desing document updates and doc fixes.