Dvc.org: glossary: create Glossary page (besides Basic Concepts)

[jorgeorpinel]

"Basic Concepts" is an actual proposed section (see #550) and not related specifically to the tooltips/glossary. Furthermore, it's used all over docs, not just in the User Guide.

Should we put it perhaps in content/docs/glossary/ ?

---

UPDATE: Jump to https://github.com/iterative/dvc.org/issues/1395#issuecomment-662018300

[shcheklein]

I'm not sure I understand the proposal and the context (I have some ideas, but not sure we are on the same page). Could you clarify please?

[shcheklein]

Also, is it a good first issue?

[jorgeorpinel]

Motivation: I just find it strange that these md metafiles are found in user-guide/basic-concepts/
Also, they are more like glossary terms than basic concepts (there's overlap of course)

[shcheklein]

The idea behind user-guide/basic-concepts/ structure is to eventually drive both - basic concepts and glossary. Glossary items feeding from some frontmatter entries, or summarizing basic concepts articles in some other way.

I think that should be more or less enough and we won't need a separate glossary section.

[mformihir]

Can I start off my contribution to DVC with this issue, @jorgeorpinel ?

I've looked up for 'basic concepts' on the DVC website and this is the page I got: basic-concepts
I suppose this issue has already been worked on? If it is the case, I will try another issue.

[jorgeorpinel]

Good find about https://dvc.org/doc/tutorials/interactive#basic-concepts @mformihir, thanks. This issue is still under discussion though. We'd appreciate if you can find another small one for now. And sorry for the delay but we're working very hard on releasing DVC 1.0 docs this week.

[jorgeorpinel]

I see @shcheklein but from what I remember in our discussions the glossary terms are not the same as the basic concepts. There may be some overlap but not a lot I think.

[shcheklein]

@jorgeorpinel we can try and see, my hope that they will overlap significantly.

[jorgeorpinel]

OK so let's do #550 first, and include or confirm this one then.

[jorgeorpinel]

So when I try to create an index in user-guide/basic-concepts/index.md I get this error:

I'll use a basic-concepts.md file alonside that dir for now. Cc @rogermparent

[rogermparent]

@jorgeorpinel I just looked into the issue and found it's easy enough to fix, I just need to add an explicit exclusion for the filename index on glossary entries. Do you have a PR with some attempted content changes? If so I can adapt that, otherwise I can make a PR that sets up a dummy index page and we can add content from there.

[jorgeorpinel]

Thanks for looking into that Roger. So any other md file added there is expected to have frontmatter (otherwise app will crash)? I'm not sure it's the best approach to have a special directory like this in the middle of the content directory. That would feel more like a config or source directory. If it's going to be in content/ I think it should not have such side effects i.e. the frontmatter should be optional — only affecting the files where it's found in.

[rogermparent]

@jorgeorpinel I could either move the glossary's directory out of the content dir or make it so all md files in there without Glossary frontmatter are passed over as glossary entries.

I leave it up to the group which solution to pick, I don't really have a preference here.

[jorgeorpinel]

Let's wait until #550 is addressed (I already started with that) to decide here 🙂

[shcheklein]

I would make it optional since it will be part of the content most likely.

[jorgeorpinel]

Some comments that support having a glossary page in addition to the Concepts section (from #2083):

collect all known and important terms within the project, the product and its usage. Examples:
NumPy - https://numpy.org/doc/stable/glossary.html
AWS - https://docs.aws.amazon.com/general/latest/gr/glos-chap.html

There are discussions between developers in comments to some issues where different understanding of the same terms takes place. The Glossary page could be a place to refer to as the reference.

[shcheklein]

Yep, we can build an index page like this from frontmatter headers. And make it an index in the Basic Concepts, or make a separate auto-generated page.

[jorgeorpinel]

There are some unclear terms used everywhere in scope of the product. especially unclear for beginners... such confusing terms are: stage, DVC-file

@DiPaolo any other terms? Those 2 have been gone from our docs since #1366, any other ones besides what you can currently find in https://github.com/iterative/dvc.org/tree/master/content/docs/user-guide/basic-concepts ? (those are currently shown as tooltips throughout the docs)

But I get that those terms are still in the tool itself (see iterative/dvc/issues/3960) so also any others in that category that you can find please list here 🙂