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-857923802

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

[me-heer]

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 🙂

[iesahin]

What do you think about renaming current basic-concepts dir to glossary and adding concepts separate from glossary entries? We can have 5-10 BC documents (e.g. that discuss #53) and can extend the glossary with any number of small definitions.

Another way is having two different kind of documents in basic-concepts that we link from the sidebar and not. For some documents there will only be glossary entries and they can be used with <abbr> tags. For others we can create links on the sidebar and use <abbr> tags when we need to use their tooltip: frontmatter.

@jorgeorpinel @shcheklein

[jorgeorpinel]

The glossary page proposed here is separate from the Concepts section. It would basically be a single page with all the tooltips dumped into some order. Auto-generated by the engine. The Q is whether we want/need that.

[iesahin]

It may be possible to have a collected tooltips page as a glossary. Some BC pages can be written in a tooltip only fashion, without linking them from the sidebar. They will be listed in doc/glossary. If there is a BC page for it, it will be linked in tooltips and in the glossary, otherwise, only a definition will be provided.

I'm putting [📖] (link to BC doc) kind of self-referencing links at the end of tooltips for BC documents. So workspace will have a link to read more about it, while external dependency will only have a definition. Is that OK? @jorgeorpinel @rogermparent

[jorgeorpinel]

Linking from tooltips to concept pages is quite reasonable. Not very related to this issue though. Thanks

[casperdcl]

summary: @iterative/docs decided that we'd like the contents of https://github.com/iterative/dvc.org/tree/master/content/docs/user-guide/basic-concepts to be auto-rendered in a single page titled "Glossary" at https://dvc.org/doc/user-guide/glossary.

[rogermparent]

we'd like the contents of https://github.com/iterative/dvc.org/tree/master/content/docs/user-guide/basic-concepts to be auto-rendered in a single page titled "Glossary" at https://dvc.org/doc/user-guide/glossary

Cool! This is certainly well within standard Gatsby stuff, so getting the data onto a specific page should be a breeze. We should be able to use the src/pages directory like we do for a few other static pages (i.e. src/pages/doc/user-guide/glossary). If somehow nested directories don't work here, we should still be able to figure something else out without too much trouble.

Once the page is there, the query should be pretty easy as well- we can model the new query after the existing one we use for the tooltips and render it into a docs page template, then add an entry for the page in the proper slot in the sidebar.

Beyond that, we may want to consider design- I'm all for just reusing the style of existing docs pages, but what does everyone else think?

[casperdcl]

I'm all for just reusing the style of existing docs pages, but what does everyone else think?

agreed, something like:

# Glossary

<b id="bold-term">Bold term</b>: description text

rendered as the engine usually would.

[jorgeorpinel]

We should be able to use the src/pages directory like we do for a few other static pages (i.e. src/pages/doc/user-guide/glossary

Can the glossary contents come from the frontmatter in https://github.com/iterative/dvc.org/tree/master/content/docs/user-guide/basic-concepts ?

I think we also want the glossary to be in https://dvc.org/doc/user-guide/basic-concepts (index page) initially. It would help us advance towards #550. But no super strong opinion on this cc @shcheklein

[jorgeorpinel]

p.s. we also talked about automatic back-links to every doc where each term is mentioned as a tooltip (maybe as a collapsible section since there can be a lot). Could be a separate issue.

[casperdcl]

I think we also want the glossary to be in dvc.org/doc/user-guide/basic-concepts (index page) initially.

Strong disagree for me since basic concepts != glossary. The fact that the sources are currently in a folder called basic-concepts is misleading and should not (for now) be reflected in the auto-generated page path/title. Fleshing things out for inclusion in a Basic Concepts page should be a separate unrelated issue (#550)

[jorgeorpinel]

It's not that unrelated. Keep in mind that this has been discussed before. We want to keep the glossary and basic concepts source together. What sidebar structure are you proposing @casperdcl ? Considering Basic Concepts.

And is our glossary really a glossary (or what kind is it, rather)? We seem to only have entries for basic concepts anyway. It's kind of a basic concepts glossary (unlike a full technical glossary like https://git-scm.com/docs/gitglossary)

[julieg18]

Can the glossary contents come from the frontmatter in https://github.com/iterative/dvc.org/tree/master/content/docs/user-guide/basic-concepts ?

@jorgeorpinel I'm not sure I understand the question. 🤔 Are you' asking if we could attempt to create the page without adding to the pages directory or are you asking if we can reuse the text inside the /content/docs/user-guide/basic-concepts? If it's the first one, there's probably a way to do it. If it's the second, I'm pretty sure we can without any issues!

[casperdcl]

If it's the second, I'm pretty sure that's exactly what my original summary (https://github.com/iterative/dvc.org/issues/1395#issuecomment-857923802) was stating.

[casperdcl]

It's not that unrelated. Keep in mind that this has been discussed before.

Are you arguing with yourself? https://github.com/iterative/dvc.org/issues/1395#issue-631321564 :laughing: I was just repeating what I thought were your previous sentiments to avoid debating off-topic stuff.

We want to keep the glossary and basic concepts source together.

yes, if and when we address #550. AFAIK the engineering implementation request here (https://github.com/iterative/dvc.org/issues/1395#issuecomment-857923802) is fully compatible with the #550 long-term plan. Are you saying you disagree?

What sidebar structure are you proposing @casperdcl ? Considering Basic Concepts.

I... don't understand. Why are we constantly discussing Basic Concepts #550? You even titled this issue "besides Basic Concepts."

Sidebar structure for the Glossary isn't something I wanted to bother @julieg18 / @rogermparent with atm but I was thinking third item under User Guide (below What is DVC? & Project structure since it seems related to both) but fine with putting it elsewhere. If you are asking whether it should also itself be collapsible (like Command Reference) I don't really think so but again no strong opinion.

And is our glossary really a glossary (or what kind is it, rather)? We seem to only have entries for basic concepts anyway. It's kind of a basic concepts glossary (unlike a full technical glossary like git-scm.com/docs/gitglossary)

It is precisely the "full technical glossary" you linked. We do NOT have entries for basic concepts. By "entries for basic concepts" I mean detailed explanations (as opposed to brief tooltip/glossary entries). I suspect by "entries for basic concepts" you mean the limited number of terms, in which case I'd say selecting some (probably just the current terms) to flesh out the hypothetical Basic Concepts for #550 is a different topic (namely, #550 :confounded:), while adding more brief terms to flesh out the current proposed Glossary is also a different (follow-up) issue.

I don't know what a basic concepts glossary is - to me it's an oxymoron. One year ago I think you would've agreed? https://github.com/iterative/dvc.org/issues/1395#issue-631321564

I suspect we're speaking 2 different languages & have 2 different ideas which means 4 different misunderstandings. Maybe another meeting lol?

The key thing is please state if you find this request wrong: https://github.com/iterative/dvc.org/issues/1395#issuecomment-857923802

[iesahin]

I think we need to discuss the relation between BC and glossary (maybe with some presentations from both of you) in the meeting. @jorgeorpinel @casperdcl

[julieg18]

Should we go ahead and start on this issue, or are do we need more discussion on the naming/placement?

[casperdcl]

I believe everyone's agreed on

• https://github.com/iterative/dvc.org/issues/1395#issuecomment-857923802 (initial one-line request)
• https://github.com/iterative/dvc.org/issues/1395#issuecomment-857985172 (@rogermparent's summary)
• https://github.com/iterative/dvc.org/issues/1395#issuecomment-858095756 (basic format)

while all the the subsequent discussion was about minor detail best addressed after we have a first PR?

[jorgeorpinel]

If it's the second, I'm pretty sure we can Should we go ahead and start on this issue

@julieg18 yes: I meant that we want to use the existing frontmatter content from the files in /content/docs/user-guide/basic-concepts (tooltip texts). Whether or not you need to crate a page or any other element in the engine is up to you 🙂

I think we're good to go with this issue's implementation (ready when you are) like @casperdcl summarized in https://github.com/iterative/dvc.org/issues/1395#issuecomment-865865652. I'm just unsure about the nav (discussion to follow) but we can probably hash it out during the PR review.

I was thinking third item under User Guide...

@casperdc I should've clarified earlier that I'm referring to the URL path / general nav hierarchy, not exact order or collapsibility (BTW I also don't think so).

[jorgeorpinel]

Are you arguing with yourself? 😆

@casperdc maybe. More precisely with myself from over a year ago (that comment is old). Like I mentioned it has been a long discussion. And still it's not clear since, again, we seem to be building a Basic Concepts Glossary after all.

Are you saying you disagree?

Summarizing, I'm just unsure about the nav at this point. The more I think about it, the more I like the idea of putting the "glossary" in guide/basic-concepts instead. Another benefit is that it will help us get going with #550 which otherwise may take very long to publish.

I think we should try to decide nowish (yes, taking into consideration the future Basic Concepts section) to avoid an unnecessary redirect later.

By "entries for basic concepts" I mean detailed explanations... need to discuss the relation between BC and glossary in the meeting

Good idea @iesahin let's retro about what we each mean by DVC concepts and glossary. We shall report back ⌛

[jorgeorpinel]

let's retro about what we each mean by DVC concepts and glossary

Update: we agreed that we can start with all the current tooltips and be flexible about what else to include. But ideally only DVC-specific terms I think. We'll manage it as it comes.

I forgot to discuss about the nav though 🤦 but please ping us from the PR @julieg18 and we'll decide then. Thanks all

[julieg18]

Pull request opened!