`plots`: move explanations from cmd ref to guide

[dberenbaum]

My only larger concern here is that there's too much info. in the command reference. We should move a good part (probably most) of the new content to the dvc.yaml schema "guide". For more specific ideas see the following comments:

• https://github.com/iterative/dvc.org/pull/3691#pullrequestreview-1022181003 (use a table for top-level plots: syntax)
• https://github.com/iterative/dvc.org/pull/3691#discussion_r918511603 (summarize top-level plots explanation in ref. and move all syntax to dvc.yaml guide)
• https://github.com/iterative/dvc.org/pull/3691#pullrequestreview-1045833093 (move dvc plots examples to sub-command refs?)

Other less important stuff:

• [x] Provide more motivation for having plot definitions at the top level. See https://github.com/iterative/dvc.org/pull/3691#pullrequestreview-1026703393 and https://github.com/iterative/dvc.org/pull/3691#pullrequestreview-1041178810
• [ ] Think through plots ref examples - https://github.com/iterative/dvc.org/pull/3691#pullrequestreview-1045830331
• ~~Update Metrics and plots section (dvc.yaml guide)? https://github.com/iterative/dvc.org/pull/3691#issuecomment-1181275871~~
• [x] Does the plots show ref need an update too? https://github.com/iterative/dvc.org/pull/3691#pullrequestreview-1035149248
• [x] Consistent terminology - https://github.com/iterative/dvc.org/pull/3691#discussion_r918496081
• [x] Mention top-level plots in stage outs field desc. https://github.com/iterative/dvc.org/pull/3691#discussion_r922885875
• [x] Remove Types of metrics from metrics ref. https://github.com/iterative/dvc.org/pull/3691#pullrequestreview-1024053543

---

• [ ] See that core texts match usage blocks. See https://github.com/iterative/dvc.org/pull/3691#pullrequestreview-1051588011 below.

Originally posted by @jorgeorpinel in https://github.com/iterative/dvc.org/pull/3691#pullrequestreview-1045840235

[dberenbaum]

• [x] ... ideally we would dissolve the examples into the explanations themselves then, as suggested here.
• [ ] Unrelated but should we rename this Custom Vega templates since there's a Custom HTML templates H2 right after this?
• [ ] Separate "guide" info from "ref" info.

[jorgeorpinel]

Sorry to back pedal here but we may have gone too far in removing everything from the plots ref 😅 . Maybe we need a mixed approach like in https://github.com/iterative/dvc.org/pull/3414#issuecomment-1225447923. Hopefully after we figure that one out (re params) we'll have a solid framework.

[dberenbaum]

@jorgeorpinel Do you think there's anything left to do here?

[jorgeorpinel]

• [ ] Think through plots ref examples

The cmd ref examples could use some grouping and possibly renaming, esp. in https://dvc.org/doc/command-reference/plots/show which has too many IMO.

• [ ] rename this Custom Vega templates since there's a Custom HTML templates

Still an open question (which also relates to .../plots/show#custom-html-templates)

• [ ] Separate "guide" info from "ref" info

I think we did that for all refs except maybe https://dvc.org/doc/command-reference/plots/templates which still feels too heavy/deep. Should be self-containted, yes, but brief. Longer explanations, technical details, even some formal definition may be better in the guide.

[jorgeorpinel]

p.s. may also want to reconsider the plots part of https://github.com/iterative/dvc.org/issues/2572 . Do we need separate plots-related guides (or perhaps file references) besides what's now inside Exp Mgmt?

[dberenbaum]

Don't think we have time to prioritize the tail of tasks here.