guide: "Comparing Experiments" improvements

[jorgeorpinel]

Extracted from https://github.com/iterative/dvc.org/pull/2862#pullrequestreview-781399419 etc.

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

General

• [x] Needs detailed copy editing. E.g. missing "the", disjointed paragraphs, unnecessary scrolling blocks, etc. (another e.g.)
• #3160 ?
• [ ] Review "baseline" concept. Apply to explanations and branch names? Per https://github.com/iterative/dvc.org/pull/2862#pullrequestreview-781399419
• [ ] Cover exp show first (exp list later). Per https://github.com/iterative/dvc.org/pull/2862#discussion_r730339949

Specific ideas

• [ ] Address https://github.com/iterative/dvc.org/pull/2908#pullrequestreview-775523131 .
• [ ] Cover deps/dependencies column. See #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 https://github.com/iterative/dvc.org/pull/2966 .
• [ ] Avoid terms "git ref" and "attached". (Use "based on" for consistency?)
• [x] --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?).
• [x] Shorten JSON/CSV output sample blocks and remove corresponding schema descriptions (comprehensive examples are enough). (See https://github.com/iterative/dvc.org/pull/2862#pullrequestreview-783758097 and below.)
• [ ] Format CSV samples if possible (even if that's not how they're output exactly)
• [x] Clarify exp diff sections to separate cases: workspace vs. HEAD, rev A vs rev B, etc. (See https://github.com/iterative/dvc.org/pull/2862#pullrequestreview-783894016 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?

[iesahin]

I have split the doc into two in #3011 @jorgeorpinel. It may be easier this way, PTAL.

[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 https://github.com/iterative/dvc.org/pull/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