refactor README and installation instructions

[joelberkeley]

I've been looking at doing a good overhaul of the docs, to

• make it easier for newcomers
• reduce duplication

and wanted to get early feedback. Do be completely honest. Is this helpful? I have an idea to work on the docs much more widely, so the approach here (short, to the point) is as important as the content.

[joelberkeley]

I'm a bit cautious of changing the README, since it's the first thing people see on the repo. But generally, this looks okay. I've left some comments on the files : )

Indeed. That's why I want to get good feedback. I haven't made any attempt to be conservative in my changes.

(Minor nitpick: I'd keep the headings in present tense. They describe an action : ) )

they are in the present tense (Present simple rather than Present continuous). Is that OK?

[joelberkeley]

I'm a bit cautious of changing the README, since it's the first thing people see on the repo

btw this is precisely why I'm working on it - because it matters

[joelberkeley]

@CodingCellist I don't have the permissions to merge this, do you?

[andrevidela]

I've got you