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:

• cmd-ref: plots: flexible plots docs #3691 (review) (use a table for top-level plots: syntax)
• cmd-ref: plots: flexible plots docs #3691 (comment) (summarize top-level plots explanation in ref. and move all syntax to dvc.yaml guide)
• cmd-ref: plots: flexible plots docs #3691 (review) (move dvc plots examples to sub-command refs?)

Other less important stuff:

• Provide more motivation for having plot definitions at the top level. See cmd-ref: plots: flexible plots docs #3691 (review) and cmd-ref: plots: flexible plots docs #3691 (review)
• Think through plots ref examples - cmd-ref: plots: flexible plots docs #3691 (review)
• Update Metrics and plots section (dvc.yaml guide)? cmd-ref: plots: flexible plots docs #3691 (comment)
• Does the plots show ref need an update too? cmd-ref: plots: flexible plots docs #3691 (review)
• Consistent terminology - cmd-ref: plots: flexible plots docs #3691 (comment)
• Mention top-level plots in stage outs field desc. cmd-ref: plots: flexible plots docs #3691 (comment)
• Remove Types of metrics from metrics ref. cmd-ref: plots: flexible plots docs #3691 (review)

---

• See that core texts match usage blocks. See cmd-ref: plots: flexible plots docs #3691 (review) below.

Originally posted by @jorgeorpinel in #3691 (review)

[dberenbaum]

• ... 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 #3414 (comment). 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 #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.