Dvc.org: glossary: add <abbr> tags everywhere!
Once #431 is merged,
There will be an initial glossary.js file with a set of terms we want to add <abbr> tags around in the md files so they display glossary tooltips on hover and dotted underline links to click on (for mobile).
[x] Implement mobile view
per https://github.com/iterative/dvc.org/pull/431#pullrequestreview-263985560@algomaster99[ ] Add missing glossary terms listed on #424.
[ ] We have to use discretion to chose at least one occurrence of each term in all the docs to have this functionality. Note that some of these occurrences are currently linked to some other doc and would need to be unlinked (but an equivalent link should be in the glossary tooltip).
Note that the "workspace" and "DVC project" terms are already fully applied as well as "cache directory" and "the project" (but maybe not simply "cache", so start from there).Per https://github.com/iterative/dvc.org/pull/431#issuecomment-506012482 and https://github.com/iterative/dvc.org/pull/431#issuecomment-506078052
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 missing concepts. The glossary tooltips could point to these sections among other things. An example would a DVC-file term and this link: https://dvc.org/doc/user-guide/dvc-file-format~~ Extracted to #550[ ] Review the terms and their descriptions in the glossary.js file, vs. all the existing definitions in md docs, possibly making the ones in docs shorter now that we can have the glossary tooltip over those occurrences of each term.
Per https://github.com/iterative/dvc.org/pull/431#discussion_r298302607
Possibly also add functionality to the glossary engine module so all the abbr terms in each doc are displayed on the right side bar (when visible, for wider screens) beneath the edit and chat buttons.
jorgeorpinel
All 16 comments
@jorgeorpinel Let's start working on this issue now. :)
algomaster99
on 23 Jul 2019
Feel free to get going with fixing the mobile view and open a PR, sure! Thanks @algomaster99
jorgeorpinel
on 24 Jul 2019
Any luck so far with the mobile view @algomaster99 ? I can work on the other checkboxes in this issue description but that one I feel you're the best equipped to tackle.
Of all the glossary: issues, this I think is the most important one so I'm giving it p1 label @shcheklein but please correct me if i'm wrong.
jorgeorpinel
on 10 Aug 2019
@shcheklein also what do you think of the parts of the description I scratched out: "There should be a section or a few sections called Basic Concepts..." and "Possibly also add functionality to" (at the very bottom)? Please confirm we no longer need those, otherwise I'll create a separate issue for any relevant one.
jorgeorpinel
on 10 Aug 2019
@jorgeorpinel I think we still need some Basic Concepts section in the User Guide - a section per each, that explain stuff in more details than the glossary.
I agree to remove the second one for now.
shcheklein
on 10 Aug 2019
Extracted "There should be a section or a few sections called Basic Concepts..." to #550.
jorgeorpinel
on 11 Aug 2019
Ping @algomaster99 still around? 馃槂
jorgeorpinel
on 2 Sep 2019
@jorgeorpinel I am really sorry I am not contributing these days but I have been really busy. Can you quickly update me what all do I need to do as of now? Thanks!
algomaster99
on 2 Sep 2019
No worries just let us know if you're no longer available, you've already helped a lot 馃憤
But if you can try to address the first checkbox here, that would be great:
- Fix mobile view first, actually. Per https://github.com/iterative/dvc.org/pull/431#pullrequestreview-263985560
jorgeorpinel
on 2 Sep 2019
- Fix mobile view first, actually. Per https://github.com/iterative/dvc.org/pull/431#pullrequestreview-263985560
I am just temporarily busy. I will definitely get on with this issue once I am free. I'll try this weekend.
algomaster99
on 2 Sep 2019
Fix mobile view first, actually. Per https://github.com/iterative/dvc.org/pull/431#pullrequestreview-263985560
Actually I looked with my browser (Chrome) and mobile view is not broken by this, it's just not implemented yet. What are the options to implement this? The floating tooltips don't seem to be a good design for mobile. Maybe create a rectangle in the bottom 1/3 or so of the screen for the glossary entry text? (With an x to close it.)
jorgeorpinel
on 24 Sep 2019
@jorgeorpinel We can give small question mark to indicate if it is clickable on mobile. Something like this - cache? or should we stick with underline only?
For display, I agree with showing it on 1/3 of screen.
algomaster99
on 24 Sep 2019
@algomaster99 are you back? 馃檪
I think underline is fine. Honestly I wouldn't expect many people will be using our command reference on mobile that much but I guess we have to implement this. If we could just have a rectangle take over the bottom 1/3 or so of the screen (with a big x to close it) when they click underlined terms, that would be great.
jorgeorpinel
on 24 Sep 2019
@jorgeorpinel can we close this one?
shcheklein
on 7 May 2020
It hasn't been finished actually 馃槄 the use of tooltips is not super consistent yet. But if we plan to just keep doing this going forward and not retroactively, then yes.
jorgeorpinel
on 7 May 2020
Yeah, I doubt that we'll have time to go through all the pages at some point. Let's close it.
shcheklein
on 7 May 2020
Related issues
jorgeorpinel
路
3Comments
piojanu
路
4Comments
jorgeorpinel
路
4Comments
algomaster99
路
4Comments
efiop
路
4Comments