Dust off the `README.md` and pick some other nits

[webbnh]

This PR is an accumulation of random things which I've spotted while doing code reviews and investigating other changes:

• the top-level README.md needed updating
• a couple of files were suffering from cut-and-pastage
• the docs/.gitignore file was missing its trailing newline.