guide: new DVC Concepts section

[jorgeorpinel]

Per #431 (review)

There should be a section or a few sections called Basic Concepts in the user guide that is/are properly written on a user-level language explaining some concepts. The glossary tooltips could point to these pages too.

we need to explain concepts like Cache, Remote, Wokspace, etc, and their relationships (with diagrams if needed).
From #550 (comment) below

Figure out a connection to glossary tooltips (currently special md files with Frontmatter in content/docs/user-guide/basic-concepts/ — see #1395): Just link to the Concepts? Use a similar engine (with Frontmatter)? Merge completely?

UPDATE: Skip to #550 (comment) for summary

UPDATE: Specific plan

Use contents from #1655 as needed.

• Do we need the changes in package.json, src/components/Documentation/Markdown/Tooltip/index.tsx, src/gatsby/models/glossary/index.js, and src/utils/front/glossary.ts from [WIP] concepts: move from previous docs to new section, etc. #1944 ?
• Workspace (added a BC: workspace document #2197)
• DVC Project (vs. Git/DVC Repository) [guide: DVC Project concept page #2754]
• (from cmd ref) (DVC) Metafiles
• (from cmd ref) DVC/Project Cache
• (from cmd ref) Data Pipeline(s)
• (from cmd ref) Metrics & Plots
• (from cmd ref) Remote (Storage)
• (from cmd ref) Stage
  & update some of the links around this term that currently go to run/stage.
  (Some should link to the future pipelining guide, see guide: Modeling Pipelines #2883)
• (from cmd ref) (Stage) Output
• (from cmd ref) (Stage) Dependency
• Run-Cache?
• Garbage Collection clarifications (in cache or remote pages, see concepts: doc garbage collection in cache and/or remote concept pages #2169)
• Workspace clarifications? Discussed in term: ambiguous use of "external" and "workspace" #1127
• Add Further Reading sections to all Basic Concepts documents? ([v1] misc. (old) cmd ref updates #2127)

---

• Look into glossary: create Glossary page (besides Basic Concepts?) #1395 after or along with this one.
• Consider also a related DVC Principles section (more philosophical, maybe in the Concepts section index)? See guide: new DVC Concepts section #550 (comment) below.
  UPDATE: Maybe use the section index for this or/and What is DVC?.

[shcheklein]

• @jorgeorpinel also, this one is related - user-guide: cache/remote/workspace relationships #53 . I though that one can be a part of the Basic Concepts.

[jorgeorpinel]

Perhaps we can call it DVC Principles, similar to:

From https://www.hashicorp.com/products/terraform

[shcheklein]

@jorgeorpinel it seems to me like some parts from the https://dvc.org/doc/understanding-dvc . A bit philosophical. And there should be a section like this, but also we need to explain concepts like Cache, Remote, Wokspace, DVC-file, etc, their relationship (with diagrams if needed).

[jorgeorpinel]

From #727 (comment):

• https://dvc.org/doc/command-reference/cache,
• https://dvc.org/doc/command-reference/metrics,
• https://dvc.org/doc/command-reference/pipeline, and
• https://dvc.org/doc/command-reference/remote

have useful, unique content but I'm not sure the cmd ref is the best place for those explanations.

Should we take the move the explanation about those concepts to this new guid and only leave a very stripped down index for those commands? Which could link to the Basic Concepts section, of course.

[jorgeorpinel]

Howdy @casperdcl. Other than the tooltips you've added recently (in #2359) are you still planning to work on this? Please un-assign otherwise 🙂

[casperdcl]

I'm not altogether sure what it really means to be assigned to an epic - assigned to push others to solve the individual sub-issues? Given that the title is "new DVC Concepts section" there may be others better placed to do that. Unassigning for now.

[jorgeorpinel]

Assigned in general would mean someone is working on it or plans to do so soonish. Agree that it can be misleading to be assigned to an epic but it happens e.g. #1400.

[dberenbaum]

Lowering priority. Is this still in plans at all or should we close it?