guide: expand Experiments guide #2654
Conversation
jorgeorpinel
changed the title
jorgeorpinel
changed the title
jorgeorpinel
changed the title
and move run-cache to guide intro (index)
|
@shcheklein @iesahin this is the first in a series of cascading or nested PRs to restructure the Experiments guide and move most of the details from the command ref (for now only restructuring). Should I keep it as a draft until more PRs are open against this branch? Should we start the review process for this part? (It's ready) Thanks |
|
|
||
| _New in DVC 2.0_ | ||
|
|
||
| `dvc exp` commands let you automatically track a variation to an established |
There was a problem hiding this comment.
not for this PR: track a variation to an established data pipeline sounds very complicated.
dvc exp run, dvc exp show, and other dvc exp commands automatically capture and save experiment runs, including code, data, metrics, models, etc.
or even better - get rid of this sentence :) It does more harm than good to my mind.
| experiments this way, as well as review, compare, and restore them later, or | ||
| roll back to the baseline. The basic workflow goes like this: | ||
|
|
||
| - Modify stage <abbr>parameters</abbr> or other dependencies (e.g. input data, |
There was a problem hiding this comment.
not for this PR: Modify hyperparameters (link to params), code ... etc ... we are being way too formal here again. I thinks we can sacrifice it a bit and use some common ML terminology
This comment has been minimized.
This comment has been minimized.
jorgeorpinel
changed the title
|
@iesahin @shcheklein WDYT about the changes here? Please see the description for a list (and links to the related file changes). Especially about having a dedicated DVC Experiments page to explain what experiments are and potentially go into implementation details (in the future). It would make more sense with a simplification of the Running Experiments page but let's leave that for another PR (it's a task in #2768 for now). See https://dvc-org-guide-exps-i6pyd2tmqgh.herokuapp.com/doc/user-guide/experiment-management p.s. Looks like nesting PRs wasn't very successful, this ended up being quite a big PR after merging a few others back into it... Sorry! |
| @@ -0,0 +1,36 @@ | |||
| ## DVC Experiments | |||
There was a problem hiding this comment.
it should be clear that those are DVC experiments?
also it's clear that this is about experiments
what is the actual intention behind this page?
There was a problem hiding this comment.
also, renaming page + copy editing makes it almost impossible to review
There was a problem hiding this comment.
Currently the section in the index is just called Experiments and I'm happy to rename it back to that. I just thought it would be clearer to "brand them" since they're special. We also say things like DVC Project, DVC Cache, and DVC Remote.
actual intention behind this page?
"...dedicated DVC Experiments page to explain what experiments are and potentially go into implementation details (in the future)." 🙂
renaming page + copy editing makes it almost impossible to review
This is a brand new page. No file was renamed in this PR. Some of it's info was extracted from the index.md.
There was a problem hiding this comment.
p.s. I realize it's a huge PR. That's because we wanted to try nesting PRs, but it resulted in this one being too big and losing track of which changes we already approved... But the PR description has a list of changes done with links to the files updated (4 major ones). Everything else is small copy edits and link updates.
There was a problem hiding this comment.
clearer to "brand them" since they're special. We also say things like DVC Project, DVC Cache
In fact we already call it "DVC Experiments" in some places e.g. there's a few instances in https://github.com/iterative/dvc.org/pull/2901/files#diff-8bac2dee1e13766aefa536c3d2fa38296dc6b09ba750fd71c9eedde61df8d1b9
| cleans the slate so you can repeat the process. | ||
|
|
||
| ## Checkpoints in source code | ||
| Every time you [reproduce](/doc/command-reference/repro) a pipeline with DVC, it |
There was a problem hiding this comment.
sounds too much for the index page? and too abrupt to be honest (even though it is in the details section)
|
|
||
| > 📖 To learn more, see the dedicated | ||
| > [Checkpoints](/doc/user-guide/experiment-management/checkpoints) guide. | ||
| ## DVC Experiments |
There was a problem hiding this comment.
same here - it's clear that this is about dvc and about experiments - what is the intention of this subsection? what is the intention behind the index page?
|
|
||
| ### Organization patterns | ||
| ### Organization Patterns |
There was a problem hiding this comment.
should it be somewhere inside? (not on the index page)?
|
@jorgeorpinel there are indeed too many changes at once, some of them are not that related. Could you please split this? otherwise we'll have a few reviews happening at once in one PR - it can take forever to do this :) |
|
OK. I'll split this ⌛ |
Extracted to #2908 |
Extracted to #2909 |
Extracted to #2910 |
* guide: Review of + link checkpoints guide from #2654 (comment) * guide: remove `dvc experiment` links * guide: roll back unrelated changes
jorgeorpinel
added
type: enhancement
Restructures the guide into an intro and a few pages.
Per #2548 (main files changed linked in each item below)
ReviewCopy edit Checkpoints guide for now.Can it be broader yet shorter?Move deep details from https://dvc.org/doc/command-reference/exp/run#checkpoints
Done in guide: revisit Checkpoints guide(s) #2753 (not nested)
Extracted to guide: revisit Checkpoints guide(s?) #2769
Potentially:
dvc expfrom the cmd ref.exp push --run-cache(Sharing Exps) #2687