Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

ref: extract technical details from exp run to guides #3182

Merged
merged 23 commits into from
Jan 28, 2022
Merged

Conversation

jorgeorpinel
Copy link
Contributor

@jorgeorpinel jorgeorpinel commented Jan 12, 2022

For tasks in #2548

  • extract technical details from ...reference/exp (esp. run) to guides

Most of the material should already be in guides.

and per #2768

  • The pipeline section seems too deep...
  • The text under (Hyper)parameters has nothing to do with running experiments

@shcheklein shcheklein temporarily deployed to dvc-org-ref-exp-pmsxtvqwhk3xsn January 12, 2022 23:19 Inactive
@jorgeorpinel jorgeorpinel self-assigned this Jan 12, 2022
@jorgeorpinel jorgeorpinel temporarily deployed to dvc-org-ref-exp-pmsxtvqwhk3xsn January 12, 2022 23:34 Inactive
@jorgeorpinel jorgeorpinel temporarily deployed to dvc-org-ref-exp-pmsxtvqwhk3xsn January 12, 2022 23:40 Inactive
@jorgeorpinel jorgeorpinel temporarily deployed to dvc-org-ref-exp-pmsxtvqwhk3xsn January 12, 2022 23:41 Inactive
Alrd (hidden) in Exps Overview
@jorgeorpinel jorgeorpinel temporarily deployed to dvc-org-ref-exp-pmsxtvqwhk3xsn January 12, 2022 23:44 Inactive
@jorgeorpinel jorgeorpinel temporarily deployed to dvc-org-ref-exp-pmsxtvqwhk3xsn January 12, 2022 23:54 Inactive
@jorgeorpinel jorgeorpinel temporarily deployed to dvc-org-ref-exp-pmsxtvqwhk3xsn January 13, 2022 00:02 Inactive
@jorgeorpinel jorgeorpinel changed the title ref: extract technical details (esp. run) to guides ref: extract technical details from exp run ref. to guides Jan 13, 2022
@jorgeorpinel jorgeorpinel requested a review from iesahin January 13, 2022 00:02
@jorgeorpinel jorgeorpinel marked this pull request as ready for review January 13, 2022 00:02
@jorgeorpinel jorgeorpinel changed the title ref: extract technical details from exp run ref. to guides ref: extract technical details from exp run to guides Jan 13, 2022
@jorgeorpinel jorgeorpinel removed the request for review from iesahin January 13, 2022 00:34
@jorgeorpinel jorgeorpinel temporarily deployed to dvc-org-ref-exp-pmsxtvqwhk3xsn January 13, 2022 00:49 Inactive
bring details about checkpoint tracking from exp run ref
@jorgeorpinel jorgeorpinel temporarily deployed to dvc-org-ref-exp-pmsxtvqwhk3xsn January 13, 2022 00:54 Inactive
into Running Exps and Checkpoints guides
@jorgeorpinel jorgeorpinel temporarily deployed to dvc-org-ref-exp-pmsxtvqwhk3xsn January 13, 2022 01:29 Inactive
guide: bring missing info from ref., reorg text
@jorgeorpinel jorgeorpinel temporarily deployed to dvc-org-ref-exp-pmsxtvqwhk3xsn January 13, 2022 04:22 Inactive
@jorgeorpinel jorgeorpinel temporarily deployed to dvc-org-ref-exp-pmsxtvqwhk3xsn January 13, 2022 19:13 Inactive
@jorgeorpinel
Copy link
Contributor Author

jorgeorpinel commented Jan 13, 2022

Interesting discussion (going back again to guides vs. refs): Maybe we should keep some specific "recipes" and maybe short samples/diagrams in the ref, keeping in mind user guide doesn't replace cmd refs. ⌛

Notes (from chat with @shcheklein):

  • Refs. should be self-contained (like man pages) to a reasonable extent.
  • Guides don't need to cover all the details of each command (e.g. lesser options can be described in refs only.)

Questions:

  • How much overlap is expected?
    I think that while guides mainly explain (gives understanding), refs. describe usage in practical terms (assumes understanding).
  • Which type of doc is more technical?
    I believe that while refs. are more technical in general, deeper tech details (e.g. implementation) should exist in guides only, if needed to explain motivation/behavior/limitations/advanced use.

@jorgeorpinel jorgeorpinel temporarily deployed to dvc-org-ref-exp-pmsxtvqwhk3xsn January 18, 2022 02:19 Inactive
@jorgeorpinel jorgeorpinel temporarily deployed to dvc-org-ref-exp-pmsxtvqwhk3xsn January 18, 2022 02:42 Inactive
into a single section and make Results another section
@jorgeorpinel jorgeorpinel temporarily deployed to dvc-org-ref-exp-pmsxtvqwhk3xsn January 18, 2022 03:30 Inactive
@jorgeorpinel jorgeorpinel temporarily deployed to dvc-org-ref-exp-pmsxtvqwhk3xsn January 18, 2022 04:35 Inactive
and move parallelism details back to the ref..?
@jorgeorpinel jorgeorpinel temporarily deployed to dvc-org-ref-exp-pmsxtvqwhk3xsn January 18, 2022 05:01 Inactive
jorgeorpinel added a commit that referenced this pull request Jan 18, 2022
other misc. related changes

Extracted from #3182
@jorgeorpinel jorgeorpinel temporarily deployed to dvc-org-ref-exp-pmsxtvqwhk3xsn January 18, 2022 05:45 Inactive
@jorgeorpinel jorgeorpinel dismissed iesahin’s stale review January 18, 2022 05:52

Thank you! Contents have changed a lot though.

@jorgeorpinel
Copy link
Contributor Author

@shcheklein PTAL at changes per #3182 (comment). The summary under #3182 (review) has been updated as well. Thanks

@jorgeorpinel jorgeorpinel requested review from shcheklein and removed request for shcheklein January 28, 2022 01:59
@shcheklein shcheklein merged commit 1dd24eb into master Jan 28, 2022
@shcheklein shcheklein deleted the ref/exp branch January 28, 2022 03:39
iesahin added a commit that referenced this pull request Apr 11, 2022
* guide: link from exp init intro to -i example in ref.

* ref: simplify note about repro in exp run

* ref: remove details about dvc exp codification

* ref: remove motivation for using exp run
Alrd in Running Exps

* ref: remove emphasis on exp run --name
Alrd (hidden) in Exps Overview

* guide: bring exp show/diff/apply links from exp run ref
into Running Exps

* guide: bring details about clearing exps from exp run
into Cleaning Up Exps

* guide: simplify Checkpoints intro and
bring details about checkpoint tracking from exp run ref

* ref: dissolve checkpoints details from exp run
into Running Exps and Checkpoints guides

* ref: remove exp run --queue details and
guide: bring missing info from ref., reorg text

* ref: remove exp run --jobs details (parallel queue exec)
Alrd in Running Exps

* ref: format fixes in exp run

* ref: remove details on queued checkpoint exps from exp run Desc.
It's mentioned in the Options (revised).

* ref: simplify example in exp run
merge explanation into corresponding guide

* Update content/docs/command-reference/exp/run.md

Co-authored-by: Emre Sahin <[email protected]>

* ref: describe all major features of exp run
per #3182 (comment)

* checkpoints: remove "in-code" term

* guide: consolidate pipeline-related info in Running
into a single section and make Results another section

* guide: compress Params section in Running Exps

* guide: summarize the Exps Queue section of Running Exps
and move parallelism details back to the ref..?

* guide: undo changes to Checkpoints guide
extracted to #3189

Co-authored-by: Emre Sahin <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

exp run --reset : Clarify behavior
3 participants