create glossary

[jorgeorpinel]

From #321 (comment)

• Create new Glossary doc with definitions to relevant DVC concepts and terms. Use appropriate links to other docs in these definitions.
• Mention to "utilize the terminology listed in the glossary(linked) consistently" in the docs contrib guide.

---

UPDATE: Main terms that can be grouped in single entries, and related terms to connect with or disambiguate from (ideas):

• Workspace, DVC project - related: SCM repository, working directory
• DVC meta files and directories (in '.dvc/' dir) - related: DVC config file, DVC cache
• Data artifact, data - related: versioning
• DVC cache, cache, "the cache" - related: file checksum, file link, innode, remote cache
• DVC-file - related: stage file, .dvc file extension, Dvcfile file name, orphan stage file
• DVC remote, remote cache - related: remote location (see external deps/outs guides), cache
• Pipeline, data pipeline - related: DAG, stage
• Stage, pipeline stage - related: stage file, DVC-file
• DAG, dependency graph - related: pipeline
• Project metrics
• DVC workflow? - related: workflow, Git workflow, experiment workflow

(but in alphabetical order)

[kurianbenoy]

I would like to work on this after completing #396

[shcheklein]

@kurianbenoy sure! but let's coordinate here first with @jorgeorpinel, what terms we should put into Glossary, their definitions, etc.

[algomaster99]

To start the list, here are a few suggestions:

• Pipeline/computation graph
• Cache and workspace
• Metric
• Dvcfile

[ryokugyu]

@kurianbenoy let's work together on it. I am also working on a tutorial which is about to complete.

[ryokugyu]

To start the list, here are a few suggestions:

• Pipeline/computation graph
• Cache and workspace
• Metric
• Dvcfile

Further,

• repro
• staging
• remote
• lock
• workflow

[shcheklein]

Related #296 . I would say glossary should be very simple and it's main purpose probably to serve as an index and as a guide for contributors. While #296 should introduce DVC concepts like cache, workspace, etc in more details.

[algomaster99]

@shcheklein Who is working on this? I can take this up if it is unassigned. :)

[shcheklein]

@kurianbenoy have you started working on this? @algomaster99 it would be great, please coordinate with @jorgeorpinel on this as well.

[jorgeorpinel]

Thanks for all the interest guys. I came up with this suggestion mainly for some key concepts that aren't really explained in user guides and which probably don't need a full doc each.

Some of the terms you have listed above I think are already well explained though, so they may not need a glossary entry. Or maybe we can list them in the glossary without a description, just linked to an appropriate user guide/get started chapter/command ref.

We need to explore the docs in full to ...
UPDATE: See updated issue description.

[jorgeorpinel]

Hi. Please see the updated description and notice that a good way to browse for terms that should probably be listed in the glossary and linked to in their original documents is searching for **bold** and _underline_ terms.

Should we also remove all these bold/italic and just link instead @shcheklein ? As well as search for all these terms everywhere to find instances that are NOT in bold/italic, in order to link or somehow mark those too.

Suggestion: I think at least the first occurrence of glossary terms in each document should be linked, and subsequent ones can remain in bold or underline. I also vote to switch to use only italic for this, since bold is already widely used to emphasize some phrases in the docs. (BTW all this could perhaps be done automatically in the future.)

UPDATE: Whatever we decide should probably be explained briefly in the docs contrib guide.