Update dvc root command reference motivation and examples

[jeremydesroches]

Updates motivation and examples. See issue #404.

[jorgeorpinel]

please double-check my formatting and style

That's checked automatically by Github and Restyled (shown in the bottom PR summary). You can see all the checks in that section of the PR (inside "test", specifically yarn format-check). These should also be run locally automatically if you setup the dev env as explained in our docs contrib guide. Please lmk i fyou have questions about any of that.

[jorgeorpinel]

Hey Jeremy. Thanks for the PR.

I haven't checked the examples yet but the description didn't fully convince me.

I left specific comments ☝️

[jeremydesroches]

Thanks Jorge. Made changes based on your feedback and left comments open.

[jorgeorpinel]

Few more questions on the description. Thanks

[jorgeorpinel]

@jeremydesroches please check #404 (comment) before continuing here 🙏

[jorgeorpinel]

I noticed you added Examples @jeremydesroches. Thanks, I'll review them. But please first make sure the old ones (first 2) are "actionable and meaningful. It's should be easy to run commands to see the results", per #404

[jeremydesroches]

I noticed you added Examples @jeremydesroches. Thanks, I'll review them. But please first make sure the old ones (first 2) are "actionable and meaningful. It's should be easy to run commands to see the results", per #404

I reviewed the existing two examples before adding the new ones.

The first example is still meaningful and actionable because it's important to show that dvc root returns a relative reference when and where it's run.

I adjusted the second example to make it more a meaningful and useful (while keeping it simple). The updated version uses dvc root to specify the output of a dvc get command, while working from a subdirectory.

[jorgeorpinel]

Left some more comments above ☝️

And a review of the Examples below 👇

[jorgeorpinel]

OK... I think what we need is a shell script that generates a dvc.yaml file instead of another dvc run example. Not required for this PR, so if you're not so familiar with Linux shell just leave it out for now please. Thanks

[jeremydesroches]

I removed this for now.

I looked into some related issues (#615) and examples of scripts.

These make sense within the scripting use case but instead of adding a (complicated) example that builds out a full set of stages, it would help to have the team vet a smaller example that fits the recommended usage.

[jorgeorpinel]

OK this is ready I think. I'll just commit my couple pending suggestions and merge this.