CONTRIBUTING.md improvements

[Trott]

• Version: n/a
• Platform: n/a
• Subsystem: doc

A problem with our CONTRIBUTING.md is that it is very long and is often needlessly wordy.

Most people who are reading the doc are probably clicking through to it from the interface where they are opening a pull request or an issue.

In other words, they are just about to do something. That is a terrible time to put a super long document in front of them. Ideally, it would be a short document with just what people need.

Unfortunately, that can be in tension with other purposes/uses of CONTRIBUTING.md such as to advertise our values and be welcoming. So, removing content might hit objections.

I had intended to go through and make it more concise in a piecemeal fashion without eliminating content. See 90abfd6 for example. But then…

I went to open a pull request in ESLint and came across this magnificent example of a CONTRIBUTING.md.

Nice and short, but links out to the things you need to know. If you're opening a bug report it doesn't put hundreds of words about change requests in front of you. That sort of thing.

So, if someone wants to try to re-organize our CONTRIBUTING.md to be more like that one, I'd be 👍. Necessary caveat: There are 106 other Collaborators on Node.js and they are likely to have opinions too and their opinions may contradict mine or each other's. Doc changes are hard enough as is, but do be prepared for the too-many-cooks problem. Don't get discouraged!

[joyeecheung]

Big +1 to simplifying CONTRIBUTING.md and listing links there instead of leaving a wall of text. I would say the same should be done to COLLABORATOR_GUIDE.md as well, there are a few overlaps in those two guides, we can merge those in one document and link to that in both guides.

[mannanali413]

@joyeecheung and @Trott I can take this up.