Exploring addition of vocabulary terms to metadata and lessons. #97
Conversation
1. Add `params` key to lesson YAML header with subkeys `assumes` and `defines`, each of which stores a list of words. The former is the terms required to understand the lesson; the latter is the terms defined by the lesson. 2. Demonstrate where/how to interpolate these into lesson text. (If we adopt this approach, the four lines would be reduced to a function, and could turn definitions into hyperlinks to a glossary shared between lessons.) Thanks to @malcolmbarrett for introducing me to `knitr::asis_output`.
| @@ -8,6 +8,17 @@ runtime: shiny_prerendered | |||
| tutorial: | |||
| id: "com.rstudio.primers.02-vis-basics" | |||
| version: 1.0 | |||
| params: | |||
There was a problem hiding this comment.
Is the idea that we want these to show up in the "knit with parameters" menu in the IDE and on connect? Specifically, would we lose anything if we hard-coded a glossary YAML field into leanr docs?
There was a problem hiding this comment.
It wasn't obvious in the R Markdown docs how to access arbitrary parameter values in the body of the document: when I define the key as glossary and try to access glossary$assumes and glossary$defines, I'm told they don't exist.
There was a problem hiding this comment.
Yes, params is the only field that currently makes values available inside of a document. I don't think we should overload it, because the glossary use doesn't fit well with the params workflow.
I'm suggesting that we file an issue with learnr to build out a new field. I haven't seen as far as you here, so I'm not sure that these terms need to be called from within the tutorial to be defined---but I don't foresee anything that would prevent that, once the feature has been added to learnr (rmarkdown?).
Alternatively, we may be able to add a standard but optional glossary section to every tutorial (similar to the Table of Contents), or use the glossary terms as we use the course description (i.e. on a splash page that directs users into the tutorial).
Does this sound worth filing an issue to you? If so I'm happy to take the lead or add my support to the thread, whichever you prefer.
| assumes <- paste(params$assumes, collapse = ", ") | ||
| defines <- paste(params$defines, collapse = ", ") | ||
| glossary <- paste(c('**Terms**', '', '- **Assumes:**', assumes, '- **Defines:**', defines, ''), collapse = "\n") | ||
| knitr::asis_output(glossary) |
There was a problem hiding this comment.
I like this work a lot. I think we need to integrate it into a global system that can identify which tutorials a student should visit to learn specific terms.
My first guess is that the way to do this will be to place the terms into their own YAML field, which we can then scrape the way we scrape tutorial descriptions. I'll reach out to schedule a meeting to see if you have something in mind.
There was a problem hiding this comment.
👍 If https://github.com/rstudio-education/glossRy/ takes off the YAML entries will be keys into a shared (global) glossary that can be loaded as a package rather than raw words. The terms will then be pulled from that glossary to ensure consistency and findability, to allow linkage, and to enable internationalization.
There was a problem hiding this comment.
That sounds like a great system for definition consistency. Thanks for putting it together.
I'm referring to a second need: at some point we will need to recover this ground to make a course recommender (e.g. Need help with visual space? Here are the tutorials that cover it.) Making the terms discoverable in a standardized YAML field seems like hooks enough for that system, but this is the best stage to prepare for it if you have any ideas.
Add
paramskey to lesson YAML header with subkeysassumesanddefines, each of which stores a list of words. The former is the terms required to understand the lesson; the latter is the terms defined by the lesson.Demonstrate where/how to interpolate these into lesson text. (If we adopt this approach, the four lines would be reduced to a function, and could turn definitions into hyperlinks to a glossary shared between lessons.)
Thanks to @malcolmbarrett for introducing me to
knitr::asis_output.