Docs: address some raw edges

[igneus]

The bunch of little commits is in order to explain why each edit was made - once reviewed it's probably best to squash them.

[CLAassistant]

All committers have signed the CLA.

[igneus]

I looked into the failed check and it seems to be just a temporary outage of an external service - curl -s https://codecov.io/bash returned an HTML page instead of the expected shell script.

i.e. the failure is unrelated to my changes and the tests should pass if restarted manually.