guide: DVC Experiments Overview #2909

jorgeorpinel · 2021-10-09T00:41:47Z

Originally extracted from #2654 (comment)

The guide's index goes over Exp Mgmt in general (not only exp commands).
The new Exps Overview page explains the basic dvc exp workflow (happy path), contains implementation details (extracted from Running Exps), and introduces exp init.
Additionally, Persisting Exps is now in a single place (stand-alone guide).

OTHER possible goals (may follow-up after this PR if needed):

Explain about exp ~~IDs and~~ names? From guide: Running Experiments improvements #2768
What to say about Organization patterns?
See guide: DVC Experiments Overview #2909 (review)
and guide: DVC Experiments Overview #2909 (review)
Improve Basic workflow section motivation and clearly differentiate it from the "new" DVC Experiments workflow.
See guide: DVC Experiments Overview #2909 (review)
Create a diagram for different exp workflows? (at least the basic one)
See guide: DVC Experiments Overview #2909 (review) below.
Longer exp init section? Even rename or split from Overview? See possible structure.

some copy edits

per #2901

content/docs/sidebar.json

content/docs/user-guide/experiment-management/dvc-experiments.md

content/docs/user-guide/experiment-management/index.md

jorgeorpinel · 2021-10-10T02:06:35Z

content/docs/user-guide/experiment-management/index.md

-### Organization patterns
+### Organization Patterns

-DVC takes care of arranging `dvc exp` experiments and the data
-<abbr>cache</abbr> under the hood. But when it comes to full-blown persistent
-experiments, it's up to you to decide how to organize them in your project.
-These are the main alternatives:
+It's up to you to decide how to organize completed experiments. These are the


From #2654 (review)

should it be somewhere inside? (not on the index page)?

@shcheklein maybe, let's decide... But not in scope for this PR probably?

per #2909 (review)

per #2909 (comment)

rel #2909 (comment)

fix links

per #2909 (review)

per pending comments in #2909 (review)

dberenbaum

A few more minor comments 🙏 . If it's vital to get it merge now, let me know and I can approve, but I think one more iteration might be useful.

content/docs/user-guide/experiment-management/experiments-overview.md

per #2909 (comment)

per #2909 (review)

jorgeorpinel · 2021-12-10T17:42:21Z

@shcheklein several possible follow-ups here (see PR description) but do you think this is mergeable? Thanks

UPDATE: I removed a bunch of unrelated changes that somehow got to this PR (probably nested PR), moving to #3080

jorgeorpinel · 2021-12-13T22:02:19Z

I know there are still questions around this but they're larger than just about the index and overview page so I'm merging this much. Should be followed upon in #2911. Thanks

* ref: bring changes from #2909 * guide: bring changes from #2909 * exp: pull some changes from #2908 * ref: better explain exp apply behavior explicitly rel. #3080 (comment) * ref: exp apply destroys any canges per #3080 (comment) * ref: clarify that exp branch makes 1+ commits in the exp branch rel. #3080 (comment) * ref: link exp apply -> exp branch per #3080 (comment) * ref: clarify (again) what applies does specifically per #3080 (review) * ref: document intended apply behavior on conflicting changes per #3080 (review)

* guide: add DVC Experiments page and links + some copy edits * guide: remove checkpoint related changes * guide: remove `dvc experiments` long cmd autolinks per #2901 * guide: move run-cache section back to Exp Mgmt index bottom per #2909 (review) * guide: Exp Mgmt/ DVC Exps -> Exps Overview per #2909 (review) * guide: clear separation between Exp Mgmt index and Overview page rel #2909 (comment) * guide: single guide for Persisting Exps content and fix links * guide: begin extracting Exp details from Running to Overview rel #2909 (comment) * guide: make ToC entry for Run Cache section rel #2909 (comment) * Update content/docs/user-guide/experiment-management/index.md Co-authored-by: Ivan Shcheklein <[email protected]> * [NESTED] guide: Exp implementation details, naming into Overview (#3006) * guide: bring exp implementation details and naming from ref. per #2909 (review) * guide: copy edits to exp naming info. * guide: emphasize dvc exps are not part of Git tree in overview rel #2909 (review) * guide: ID->name in dvc exps overview per #2909 (review) * guide: ID->name in other exp guides rel #2909 (review) * guide: Visualize->Review in exp/overview/basic-workflow per #2909 (review) * guide: don't say "cleans the slate" in exp/overview/basic-workflow per #2909 (review) * giude: soften params description in exps index per #2909 (review) * guide: generalize dvc exps basic workflow * guide: Properties section in DVC Exps overview page * guide: exp init section in Exp Overview page * guide: clarify dvc exp implementation * guide: expand on Exp Overview motivation per #2909 (comment) * guide: direct language in Exp Overview/ workflow intro per #2909 (comment) * guide: mention metrics in exp init intro (Exp Overview) per #2909 (comment) * guide: intro exp init before giving specific examples of what it does per #2909 (comment) * guide: hint forach stages for hybrid exp org pattern rel. #2909 (comment) * guide: exp mgmt index copy edits * guide: mention label-based exp organization rel. https://docs.google.com/presentation/d/1C_owNoC72GvrpyMGlonHEYJ9I2rl2SLHkZQDMx0eT7A/edit#slide=id.gcb78e52e40_0_635 * guide: hide exp naming section in overview page and other details per #2909 (comment) et al. * guide: mention `exp init -i` in Overview per #2909 (comment) * guide: typo fix per #2909 (comment) * ref: exp apply copy edits per #2909 (review) * ref: mention init before exp init per #2909 (review) * guide: correct info aboug exp init in Exp Overview per pending comments in #2909 (review) * ref: link from exp init to corresponding guide * guide: make exp intro more concrete per #2909 (comment) * guide: rewrite exp init section of Exps Overview page per #2909 (review) * ref: roll back unrelated ref changes (moved to ref/exp-misc) * guide: roll back unrelated changes (moved to #3080) Co-authored-by: Ivan Shcheklein <[email protected]>

* ref: bring changes from #2909 * guide: bring changes from #2909 * exp: pull some changes from #2908 * ref: better explain exp apply behavior explicitly rel. #3080 (comment) * ref: exp apply destroys any canges per #3080 (comment) * ref: clarify that exp branch makes 1+ commits in the exp branch rel. #3080 (comment) * ref: link exp apply -> exp branch per #3080 (comment) * ref: clarify (again) what applies does specifically per #3080 (review) * ref: document intended apply behavior on conflicting changes per #3080 (review)

guide: add DVC Experiments page and links +

5e43591

some copy edits

shcheklein temporarily deployed to dvc-org-exp-dvc-exps-pa-qhfdse October 9, 2021 00:42 Inactive

jorgeorpinel mentioned this pull request Oct 9, 2021

guide: revisit Exp Sharing #2908

Merged

2 tasks

guide: remove checkpoint related changes

6b7300a

jorgeorpinel marked this pull request as ready for review October 10, 2021 01:54

jorgeorpinel temporarily deployed to dvc-org-exp-dvc-exps-pa-qhfdse October 10, 2021 01:54 Inactive

guide: remove dvc experiments long cmd autolinks

6027e15

per #2901

jorgeorpinel temporarily deployed to dvc-org-exp-dvc-exps-pa-qhfdse October 10, 2021 01:58 Inactive