Yarn: Move docs out of the yarnpkg/website repository to this one

[edmorley]

Yarn itself is great, however currently the online docs have many rough edges.

One thing that I really don't think helps, is having the docs be part of the separate yarnpkg/website repository.

If the canonical location for them was in this repository, people would be encouraged to update them along with adding new CLI flags/features, rather than having to remember to do so after that version has shipped.

[edmorley]

For example #2419 landed in v0.20.0, but there is no reference of the --verify-tree flag on:
https://yarnpkg.com/lang/en/docs/cli/check/

And #2052 landed in v0.19.0, but there is no reference of the --frozen-lockfile flag on:
https://yarnpkg.com/en/docs/cli/install

If the docs were in the same repository, the code review of the PR would have picked this up.

[Daniel15]

This was discussed in the past, and we decided to keep the documentation on the website as that's where it's most accessible. People writing documentation for new features could simply add something like "This is new in Yarn 0.24.0" to the documentation page so that people don't try to use it in older versions. Alternatively, they could add the documentation to the repo as an "unpublished" page, and we could publish all the unpublished pages once the new version is out.

If the docs were in the same repository, the code review of the PR would have picked this up.

We can still catch this in code review by asking people to submit a PR to the website and include a link to it in a comment.

I'm going to close this out as it's already been discussed in the past, but please feel free to reopen this issue if you disagree. Thank you! 😃

[ghost]

We can still catch this in code review by asking people to submit a PR to the website and include a link to it in a comment.

That would be great.

As an example, the company I work for is in the process of deploying yarn to a largish number of software engineers to evaluate yarn as a wholesale replacement of npm in our developer community.

Because we expect muscle memory to cause people to occasionally install dependencies using npm, in a project that is being managed by yarn, we are encouraging developers to use --frozen-lockfile in their CI.

However, --frozen-lockfile is not documented on the website (yarnpkg/website/#378). Therefore its use within our company is inconsistent, and we can't point developers to an explanation of the feature when encouraging them to adopt the flag in their CI.

So I'm hopeful that people can be encouraged to update the website in-sync with their feature pull requests.

As a side note, I like having the documentation on the website, as I can directly link to the feature I want someone to learn about.

[Daniel15]

Feel free to submit pull requests if you encounter gaps in the documentation. Most contributors to Yarn do so in their free time and might not have time to write comprehensive docs. 😃

[edmorley]

Most contributors to Yarn do so in their free time and might not have time to write comprehensive docs.

I can certainly empathise with this dilemma - however I see tests and docs as something equally important to the actual code changes in a PR, so if a contributor doesn't have time to add them, then the PR should remain open until someone has a chance to do so. This is the approach that projects like Django take - and it very much shows in the excellent quality of their docs.

In addition, if it were actually easier for people to add the docs (ie they were in the same repo), you might find more people would do so as part of the original PR.

This was discussed in the past, and we decided to keep the documentation on the website as that's where it's most accessible.

I'm not saying don't put the docs on the website -- just to have the canonical location for the docs be in this repo, and then either vendor them to the website repo (eg git submodules that uses the version tag from this repo of the latest release) or else on a subdomain that makes multiple version docs available (like the Django docs).