docs: clarify the zero-installs requirements

[eoingroat]

Clarifies zero-installs version requirement in the first step of the documentation; change proposed due to others' frustrations.

What's the problem this PR addresses?

Some people, not naming Chris specifically, don't notice the mention of a version requirement in the opening sentence of the configuration instructions. This is quite common when people aren't familiar with a tool and can lead to excessive frustration, which should be minimised at all costs.

How did you fix it?

This commit makes the version requirement - and what to do if it isn't satisfied - very clear by adding it as the first step. Now one truly has to be blind to miss it.

Checklist

• I have read the Contributing Guide.

• I have set the packages that need to be released for my changes to be effective.

• I will check that all automated PR checks pass before the PR gets reviewed.

[merceyz]

Note that there is a banner at the top of the page which is always visible that specifies

This documentation covers modern versions of Yarn. For 1.x docs, see classic.yarnpkg.com.

and the second sentence in that section of the documentation specifies

[...] starting from Yarn 2!

shouldn't those two already "suggest" which version is required?

[eoingroat]

Oh yes, I've had much fun at the expense of our most recent colleague to miss the banner and misunderstand the introductory sentence.

The problem being - its 'the most recent' colleague, this has happened with at least three different colleagues over the last two years.

It seems they were banner blind on their first read through, and on closer reading they dismissed it - because yarn is installed by the package manager so they assume they are up to date. This issue would not really exist if yarn 1 wasn't the one in package repo's (recommended by the project iirc?) as this subverts the readers expectations.

Adding a check as the first step is, I think, harmless whilst directly and concretely conveying the importance of the task; making version checking the one of the first debugging tasks a dev will do.

I'm specifically motivated to address this this time as the experience relayed by the most recent dev has resulted in him perceiving the docs as both complex and difficult, his frustration changing the tone he reads from informative to, and I quote, "gloating".

In general, Yarn2+, zero-installs, and the surrounding eco-system forms a critical part of our Secure and Reliable Engineering requirements (as well as protecting my own sanity) so I am keen to 'do something' about these things.

On the back of that, its probably worth asking if there is any organised effort / plan for collecting and acting on documentation feedback / similar? If so, I may look to assign some time to it.

[merceyz]

Alright, that's fair.

On the back of that, its probably worth asking if there is any organised effort / plan for collecting and acting on documentation feedback / similar?

Not specifically but PRs improving the documentation is always welcome.