there's ambiguity between the terms "stage" and "stage file"

(Emanating from #321)

• Directly affects dvc add, dvc import, and dvc run command refs.
• Indirectly affects many other docs where these terms are used. See for example the description of the dvc lock cmd ref.
• Look also double check the usage of the term “step(s)” (which should be stages). Related: #448

Definitions

From @mroutis:

You can say that stage is a node on a pipeline, and pipelines are the weakly-connected-component subgraphs of a DAG.

Internally, on the source code, stage is whatever is related to a file ending with .dvc (DVC-file or “stage file”). It doesn’t imply a “command” or an “action”, so dvc add will create a .dvc file describing the path and checksum of a file, without any instructions to generate such output

Aproach

From @shcheklein:

for the documentation we should be thinking from the user perspective first. For example, it means that stage term can be confusing for ppl who are using it to manage data

[shcheklein]

@jorgeorpinel I don’t think it’s a problem at all. It makes sense that on a code level we have a way deeper understanding and can use “advanced” terminology. From the user perspective it should be simple, it should be resonating with their needs, etc. We are not optimizing DOCs to be “compatible” with DVC code conventions.

[jorgeorpinel]

I think this is resolved now. Both terms “stage” and “stage file” still exist when appropriate, especially in pipeline-related docs.