website yarn unlink: must yarn unlink [package] before yarn unlink despite message to the contrary

https://yarnpkg.com/en/docs/cli/unlink

The example given on that page, and the message output by yarn unlink, strongly implies you run yarn unlink and then yarn unlink [package]. But it fails:

$ cd my-package
$ yarn unlink
yarn unlink v1.3.2
success Unregistered "my-package".
info You can now run `yarn unlink "my-package"` in the projects where you no longer want to use this module.
✨  Done in 0.09s.
$ cd ../my-package-user
$ yarn unlink my-package
yarn unlink v1.3.2
error No registered module found called "my-package".
info Visit https://yarnpkg.com/en/docs/cli/unlink for documentation about this command.

To make it work, unlink in the reverse order to linking: yarn unlink my-package then yarn unlink.

Nov 07 '17 10:11 avaragado

What would be a clearer text?

Nov 07 '17 10:11 Haroenv

My suggestions:

Fix the yarn unlink code so it doesn't tell people to do something that doesn't work.
In the first paragraph of the yarn unlink doc page, say explicitly that you should use the two yarn unlink commands in the reverse order to the yarn link commands.
Fix the code samples on the page so the two flavours of yarn unlink are run in the correct order, and show what yarn actually outputs in each case.

I would also look at the terminology for this page and yarn link. For someone unfamiliar with the commands (the target audience for this page) it's easy to become confused between the two packages: "The package you want to link" and "current project" are pretty vague/ambiguous terms. "Package" and "project" are fundamentally synonymous (for example, see https://yarnpkg.com/en/docs/cli/, which saysyarn add "adds a package to use in your current package"). "Source" and "target" would be similarly ambiguous (it all depends on perspective).

The main use case is: I'm modifying a dependency of a package and want to try it out inside that package without having to publish it. So perhaps the doc should use the term "dependency" and whatever is a good, unambiguous yarn/npm way to say "a package that depends on that dependency"... "consuming package"?

Nov 07 '17 11:11 avaragado

For anyone who lands here with this problem after running the yarn unlink in the source package directory command first. To recover from this situation, you can rerun, yarn link in the source package directory, then do the yarn unlink <source-package> commands in the correct order and then finish with the final yarn unlink in the source package directory.