Improve docs for `so`

Now they include a new user warning.
Merge pull request #1186 from david-christiansen/docs

Improve docs for `so`