guide: top-level dvc.yaml sections

[dberenbaum]

Report

Update docs to better reflect that params, metrics, and plots may be either parts of stages or independent entries in dvc.yaml.

[jorgeorpinel]

Related to #2572? (Maybe dupe)

We have also discussed moving some or all of https://dvc.org/doc/user-guide/project-structure into a new "File Format Reference" section. Thoughts?

[dberenbaum]

Closing in favor of #2572

[skshetry]

I wish we had a good name for this. Top-level plots/params/metrics is an odd naming,
even more so in the internals. :)

[jorgeorpinel]

Agreed. Has been discussed too but probably merged in that way to docs as a temporary measure. In general I think we can avoid using special names that emphasize technical details like where the plots/params/metrics are defined in a YAML file. They're all still just regular plots/params/metrics.

[skshetry]

But I think the problem goes beyond just the naming, we have two places to write a metadata for plots/params/metrics. Maybe we should just document the top-level ones, and slowly deprecate the pipeline-level from DVC.

[skshetry]

Or maybe call top-level ones simply plots/metrics/params and stage-level ones to be Pipeline artifacts/plots/metrics/params?

[dberenbaum]

@skshetry Maybe better to discuss in #3763?