update the docs for clarity and layout.