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.

[ryokugyu]

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

[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]

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.

[shcheklein]

I agree with both - linking it once and removing bold, italic, etc. We definitely should be doing this automatically. I would prefer to have something like Github does when you specify Fixes ### - it provides a hover message + and a nicely done way to highlight the link.

[jorgeorpinel]

Sounds like the glossary relates to several special features desired that would have to be built into the docs engine. Perhaps the glossary should be based on a JSON file instead of an MD file, and from therer the engine can load all the terms in order to provide links, tooltips, and generate the glossary page?

cc @algomaster99

[algomaster99]

@jorgeorpinel Even I was thinking this! Yeah, will try doing that way.