guide: move Exp org patterns to Persisting Exps, improve

[jorgeorpinel]

rel. #2939

• Merge paragraphs above and below.
• Add examples? (e.g. tree-like folder views, Git tree pic, etc.)

[jorgeorpinel]

Add examples? (e.g. tree-like folder views, Git tree pic, etc.)

WDYT @shcheklein @iesahin ? Should we add some visual examples to each tab?

[iesahin]

It's visually nicer but I'm not sure this is a good way to use tabs. Tabs are used, in general, not for overlapping content but for clearly distinct alternatives: Programming languages, operating systems, etc. The reader sees the tabs more than the content inside them, so I'd use the tabs for content rather conservatively.

[iesahin]

Also, it becomes too much work to read all. We expect the reader to read and understand all these options, not select and apply one them.

[jorgeorpinel]

Tabs are used, in general, not for overlapping content but for clearly distinct alternatives

Not sure what overlapping means here. I think the org patterns are clear alternatives. I don't think we have to limit tabs use to languages or platforms although that's their original intention indeed.

[shcheklein]

I don't have a strong opinion on this. I still think that both pages - index and overview should be significantly reconsidered (e.g. run cache on the index page is a way bigger problem), even organization patterns looks like out of the place for the index page - it's too specific information, or at least it's written this way. Point here is that most likely users won't understand this section anyway here, so no strong opinion on this :)

I would move this into the Persisting experiments. Index and Overview - should be about bigger picture, general workflow diagrams, benefits, help users better navigate in the section stucture (map subsections to the workflow), etc.

[jorgeorpinel]

Index and Overview - should be about bigger picture, general workflow diagrams, benefits, help users better navigate in the section stucture (map subsections to the workflow), etc.

Agree. There's tasks for this in #2911 (updated with your notes).

I would move this into the Persisting experiments.

Good idea ⌛ (slightly related: #2846 (review))

So assuming we put it there, what do we think about using tabs? And having "freed up some screen space" that way, about adding examples for each pattern?

run cache on the index page is a way bigger problem

I could move it elsewhere or remove it ⌛🧠

[shcheklein]

So assuming we put it there, what do we think about using tabs?

My feeling that it's not a very common pattern. I've not seen tabs being used this way. Usually tabs serve as a way to customize "same" content to my mind.

[shcheklein]

Good stuff, Jorge, but before we review this, could you please help me with the context :):

What was the intention behind this PR? (I see the link to making tabs, but title says different). I'm curios was the initial problem discussed somewhere, any specific motivation?

PR itself:

• diagram is blurry and doesn't look "native" to docs
• cards are clickable and lead to Get Started, seem a bit too much to use them (use table instead?)
• arguably organizing experiments deserves it's own page or be part of the overview / intro (in some simple form)
• can we reuse some lang from the reddit post (probably even in intro) to start answering their concerns from the very beginning ...

[jorgeorpinel]

What was the intention behind this PR?

It started as a first, exploratory attempt to apply tabs. But we also wanted to figure out what to do with this Experiment Organization Patterns section so that was a secondary objective, which is now the only goal left. Not a high priority probably

link to making tabs, but title says different

I updated the title after we decided not to use tabs but forgot to change the description... Done now.

[jorgeorpinel]

diagram is blurry and doesn't look "native"

Fixed blur I think (still adapting to Macbook). The graph is from https://github.com/iterative/example-dvc-checkpoints/network ... do you mean that the labels don't seem to connect or that the style seems off? Not sure how to address the latter

cards are clickable and lead to Get Started, seem a bit too much to use them (use table instead?)

Oops, removed links.

Actually something in the site CSS won't let me make a full-width table. I tried this code and it shows it like this:

And it has borders like the cards do so either way we need custom styles to remove those if that's what you meant. Lmk

[jorgeorpinel]

arguably organizing experiments deserves it's own page or be part of the overview / intro

Idk. We've discussed this a few times and seem to go in circles. The info. seems relevant but maybe exp features don't make it easy to get to alternative organizations yet, so it could be a product issue. I think that keeping it here for now is appropriate.

can we reuse some lang from the reddit post

OK I tried incorporating some of the concepts in a304823, basically adding some more motivation to the section intro.

[jendefig]

• diagram is blurry and doesn't look "native" to docs

Sorry catching up. RIP tabs. 😢 But I do understand the points why and making the info findable with CTRL F and from the internet is of supreme importance.

☝️ Quote is what I thought to. This image needs to be branded. Shall I make a thread for Roman @jorgeorpinel ?

Also I think having a dedicated page for this is a good idea. Given the Reddit thread, maybe some blog posts with use cases on scenarios that you would use each way could be helpful? Like a series? This harkens back to Sami's "what is and experiment" presentation at the June Meetup too.

[jorgeorpinel]

This image needs to be branded. Shall I make a thread for Roman

Is it still an issue? I think it looks less odd now... Maybe I should just remove the Sep header and maybe add a caption linking to the source?

having a dedicated page for this is a good idea

Yeah but we already have 7 pages in the Experiment Management guide so unless it's absolutely clear that this is a major exp-related topic I'd try to avoid that.

[shcheklein]

Is it still an issue?

it's still blurry ... also if we have somewhere commits tree image I would try to use the same style

On separate page or making it part of the Overview/Index.

I guess for me it's hard to connect intro like decide how to organize them once completed. with directories. May be we need to add some examples? How can we bring a completed experiment into a subdirectory?

To me all these patterns are more general than persisting experiments after they done. It's more about how do you structure your project to accommodate experimentation in the first place. wdyt?

[jorgeorpinel]

it's still blurry ... also if we have somewhere commits tree image

I zoomed in as much as possible. I don't think we have any Git tree image other than custom made (2nd fig. here). If needed we can get the designer involved cc @jendefig

To me all these patterns are more general than persisting experiments

I agree. This is meant as an incremental improvement but the deeper iteration should be on the core product itself I believe, and probably the core team is thinking about it (cc @dberenbaum?). For now this is a good step forward IMO.

[shcheklein]

This is meant as an incremental improvement

I guess that's what I struggle a bit to see we had a section that was a bit more compact, arguably in a better place and now we have the same + some images (that ideally we would want to unify somehow). I'm not sure about this being an improvement to be honest. And text is confusing now since a bunch of those organizational patterns are not about dvc exp.

[iesahin]

I think instead of naming these cnn_128, cnn_512, etc. it may be more understandable to use the same words and common steps in an ML pipeline, like data augmentation, dataset1, dataset2 etc. cnn is always in the training phase, and may be different versions of model directory.