term: ambiguous use of "external" and "workspace"

[woodshop]

The term "workspace" is defined in the glossary as "Directory containing all your project files..." However advanced dvc usage allows for remote storage of external data and external dependencies. It is not clear from the docs whether the "workspace" includes external data & dependencies. Furthermore, the docs for various commands assume different definitions of workspace. For instance, dvc push does not interact with external data, but dvc checkout does. This should be clarified in the docs.

UPDATE: Go to #1127 (comment)

[woodshop]

In general, I find that several definitions could be tightened in the docs along with "workspace".

E.g. "external dependencies" and "external data" seem to refer, respectively, to stage inputs and outputs that don't reside in the "workspace" but that are nevertheless tracked by dvc. I think it would be really helpful to clarify this in the docs. At the same time, it would be useful to refer to non-external dependencies/data as "internal" to make it easier to discriminate from external. I suppose "internal" data is located in the workspace, which includes any directory that shares the same root as ".dvc" (but I might be wrong about that).

[shcheklein]

More context - https://discordapp.com/channels/485586884165107732/563406153334128681/697459286455877732

[jorgeorpinel]

Hi, sorry for the delay. Some feedback:

advanced dvc usage allows for remote storage of external data and external dependencies. It is not clear from the docs whether the "workspace" includes external data & dependencies

External dependencies, outputs, and cache are the exception to the rule. Here are some of the explanation from docs:

In any case, I don't think we really consider them part of the workspace. They are an extension of it, like Andy correctly interpreted. They are part of the project as a whole. Any suggestion on how/where best we should clarify this?

refer to non-external dependencies/data as "internal"

Thanks for the idea but I think it would be a little cumbersome to have to call deps and outs "internal" in let's say 95% of the cases just to be bring attention to the exceptions.

dvc push does not interact with external data, but dvc checkout does

dvc push does interact with external dependencies and outputs, same as dvc checkout. It uploads/copy them to remote storage. Not any more.

It is true we don't really explore the external data cases inside individual command references though. Should we try to do so?

[iesahin]

Another point regarding workspace concept is its difference from DVC project. Currently these two have different pages in BC but these two seem to overlap a lot.

Can we say a DVC project = workspace + external dependencies? (I think we cannot.) How can we make a distinction between these two?