Update docs with Tony's feedback.
Merge conflicts.