UG: Write a synopsis section to Comparing Experiments

[iesahin]

Its too long. It’s hard to make sense w/o additional help /structure.
There should be an overview at the top of it at the very least. E.g. "there are three commands that could help you compare … list, show, diff"; Brief descriptions, links to the subsections...

[jorgeorpinel]

Its too long.
There should be an overview at the top

Doesn't that make it even longer? 🙂

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

💡 instead of grouping sections by command, we could 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.)

From #2995 (comment)

[iesahin]

I try to limit the changes per PR to a minimum. In this one, I plan to write a synopsis section. In another PR I'll regroup the sections. And yet in another I'll summarize/rephrase a section. I'd like to make everything in a single pass but IME, keeping the changes limited is essential for quick reviews :)

[iesahin]

Excuse me, this is not a PR, I thought I've submitted it. This can be a tracking issue as well, yes, I'll consider these.

[jorgeorpinel]

On the logistics: small PRs are great, but issue scan be larger. No need to create an issue for every PR I believe.
On the proposed change: If the problem is that the page is long, I'm not sure adding another section (the synopsis) addresses that, unless other parts are removed or summarized at the same time.

[iesahin]

Then you recommend starting from summarizing? @jorgeorpinel

[jorgeorpinel]

Yes I would try to address the content structure first which I think is the main issue (going back to #2995). A synopsis may also be useful (Idk) but I don't think it addresses the heart of the matter.