guide: "Comparing Experiments" improvements

[jorgeorpinel]

Extracted from #2862 (review) etc.

Rel. https://dvc.org/doc/user-guide/experiment-management/comparing-experiments

General

• Needs detailed copy editing. E.g. missing "the", disjointed paragraphs, unnecessary scrolling blocks, etc. (another e.g.)
• UG: Write a synopsis section to Comparing Experiments #3160 ?
• Review "baseline" concept. Apply to explanations and branch names?
  Per guide: Comparing Experiments #2862 (review)
• Cover exp show first (exp list later).
  Per guide: Comparing Experiments #2862 (comment)

Specific ideas

• Address guide: revisit Exp Sharing #2908 (review) .
• Cover deps/dependencies column. See Dvc exp show deps #3220
• Absorb #list-experiment-names-to-use-in-scripts into #list-experiments-in-the-workspace.
• Consider tabs when commands are used as alternatives in specific example tasks (e.g. exp show vs exp diff).
• Include/mention --only-changed per ref: exp show --only-changed #2966 .
• Avoid terms "git ref" and "attached". (Use "based on" for consistency?)
• --sort/order-by/no-timestamp sections may be too detailed. Hide or just mention + link to ref.
• Merge JSON and CSV sections more somehow (tabs?).
• Shorten JSON/CSV output sample blocks and remove corresponding schema descriptions (comprehensive examples are enough). (See guide: Comparing Experiments #2862 (review) and below.)
• Format CSV samples if possible (even if that's not how they're output exactly)
• Clarify exp diff sections to separate cases: workspace vs. HEAD, rev A vs rev B, etc. (See guide: Comparing Experiments #2862 (review) and below.)
• Distinguish experiments that ran vs queued ones (exo show/list).

[jorgeorpinel]

@iesahin could you prioritize the general points as part of phase 1?

[jorgeorpinel]

Let's discuss as agreed @iesahin 🙂

Its too long. It’s hard to make sense w/o additional help /structure.

💡 instead of grouping sections by command, let's consolidate them into major actions e.g. Review existing experiments can cover basic exp show and all of exp list. Feel free to leave some things out from sample blocks (just mention options, etc.)

The other 2 general check boxes should be straightforward to address. I think.

[jorgeorpinel]

@iesahin do you need another thing to start in parallel this sprint? Addressing some tasks in there would be a good candidate. Feel free to put it in the current board if so.

[iesahin]

I've added #3160 to write a synopsis section.

[daavoo]

In #3220 new type of column depencendies/deps is included. Should we add a checklist here ?

[iesahin]

I've added, thank you for pointing this @daavoo

[daavoo]

Hei @iterative/docs , what's the ETA for this?

The current state contains a few examples using flags that doesn't exist. Should we send a P.R. for these "hotfixes" or wait for the whole rework of the page?

[jorgeorpinel]

Not planned for this quarter unfortunately @daavoo . Please do update any ref. changes missed by the core team or by us when the tool changed, and if possible quick guide updates as well. Or at least if you can create a bug report about the guide, we can prioritize that. Thanks