guide: external cache info (extracted from Use Cases) #2475
Conversation
not sure when it was changed?
in regards to external caches
and some copy edits
|
@casperdcl @iesahin please try to pre-review this if one of you has a chance soon. I'm wondering if the changes will make sense to you without much context (I did add a description above though). Thanks |
|
|
||
| Tell DVC to use the directory we've set up above as the <abbr>cache</abbr> for | ||
| your <abbr>project</abbr>: | ||
| A <abbr>cache</abbr> outside the <abbr>workspace</abbr> is called an |
There was a problem hiding this comment.
the <abbr>cache</abbr> contents (from https://github.com/iterative/dvc.org/blob/master/content/docs/user-guide/basic-concepts/dvc-cache.md) doesn't seem consistent with this para
There was a problem hiding this comment.
How so? Can you be more specific please? 🙂
There was a problem hiding this comment.
the tooltip doesn't mention anything about the cache being external, but this para is abot externally located caches. Not sure if it may cause further confusion for people who have no idea what's going on.
There was a problem hiding this comment.
Gotcha. I think that the part "by default in .dvc/cache" suggests it can be located elsewhere. And nothing there limits it from being external.
I guess that's what @iesahin's #2475 (comment) referred to as well.
| [external dependencies](/doc/user-guide/external-dependencies)) provide ways to | ||
| track and version data outside of the <abbr>project</abbr>. | ||
|
|
||
| ## How external outputs work | ||
|
|
||
| External <abbr>outputs</abbr> are considered part of the (extended) | ||
| <abbr>workspace</abbr>: DVC will track them for | ||
| External <abbr>outputs</abbr> will be tracked by DVC for |
There was a problem hiding this comment.
does the <abbr> (https://github.com/iterative/dvc.org/blob/master/content/docs/user-guide/basic-concepts/output.md) need updating?
There was a problem hiding this comment.
I don't think so. The tooltip says "by default" and it implies it can be configured to have different locations, e.g., externally in some NFS mount.
There was a problem hiding this comment.
But the page needs a concept explanation.
There was a problem hiding this comment.
Did you mean the output tooltip @casperdcl ? (I edited your comment). If so can you specify why or what part? Sorry, the connection is not obvious to me. The part about .dvc files?
But the page needs a concept explanation.
@iesahin you mean a standalone concepts page? Sure, but out of scope here 😬 (related to #2453 though)
There was a problem hiding this comment.
oops, yes wrong link. I'm complaining about a different <abbr> (output) here.
The point is
- the section title was changed from "external outputs" to "external data," and
- yet we continue using "external outputs" in this para here, while
- the tooltip is only about "outputs."
There was a problem hiding this comment.
OK.
- Context on why we don't want the page title to have the word "output": docs: clarifications around external outputs info. #2154 (review)
- True. But the section name didn't change and it is How external outputs work.
- Right, so similar to the "external cache" comment where you see possible confusion by adding an adjective to the tooltipped term? TBH I don't see the problem but maybe I'm biased.
There was a problem hiding this comment.
I have the approach where docs are not meant for us, they're meant for people who are confused are thus looking for docs. I understand, but I don't think they will. Using multiple different similar-sounding terms tends to create a sense of complexity and makes readers (consciously or subconsciously) feel lost.
There was a problem hiding this comment.
Yeah of course they're not meant for us 🙂
I just don't understand how this can be confusing. What are the similar sounding terms here? Or if you have a suggestion to improve this, maybe that would clarify your PoV.
| @@ -57,7 +57,7 @@ $ ls -a | |||
| .git code.py foo | |||
| ``` | |||
|
|
|||
| ## Example: External cache directory | |||
| ## Example: External cache directory (is preserved) | |||
There was a problem hiding this comment.
hmm, not sure I understand this?
There was a problem hiding this comment.
My intention was to clarify what the example is about. It shows that destroy doesn't affect external cache dirs. TBH I'm not sure this is the best place to show that, maybe just a brief note in the description?
There was a problem hiding this comment.
UPDATE: I see the note already exists. Changed to "Preserve an external cache directory" for now. I guess removing the example would be out of scope for this PR.
There was a problem hiding this comment.
UPDATE 2: Shoot, I went ahead and rephrased most of the example. It wasn't very clear before. Should I split into another PR @shcheklein ? See 11f5986.
jorgeorpinel
force-pushed
the
cases/shared-dev/external-cache
branch
2 times, most recently
from
62b4fed to
11f5986
Compare
* cases&how: generalizing shared dev server case and and extract guided info to new how-to * cases: rewrite intro to Sharing Res and draft a first section on storage * cases: quick updates per #2482 feedback * cases: connect cache/remote solutions to Sharing Res problem stmt per #2482 (review) * cases: move img down, reorg some Ps, remove WIP comment * ref: update destroy external cache example rel #2475 (review) * cases: add figure to Shared Resources intro * cases: wrap up Shared Resources story (1st version) * cases: fix links to old case and copy edits on the new one * cases: address minor feedback from #2482 (review) + * cases: generalize info about basic caching data optimization rel #2482 (review) * cases: higher level solution intro per #2482 (review) * cases: remove md comment... oops * cases: rewrite part about efficient processing per #2482 (review) * cases: roll back new use case * ref: remove an md ref link * guide: fix links that shouold go to now how-to * guide: better intro for shared cache how-to per #2482 (review) * cases: remove unnecessary images per static/img/resource-pool.png
Rel. #654 (comment)