Generate slides from the workbench

[multimeric]

From the instructor training and also from discussions with trainers on Slack and elsewhere, it seems to be relatively common to use some amount of slides to accompany a Carpentries workshop. This is controversial because it risks contradicting the following:

One of the cornerstones of The Carpentries teaching is live coding: instructors do not use slides to teach coding, but work through the lesson material, typing in the code or instructions, with the workshop participants following along.

However, there are a few topics on which I can see slides being valuable, and where I think instructors are using slides:

• To present figures to learners to aid their understanding. This is already somewhat supported by Workbench by the Extract All Images button, but these figures lack a consistent and friendly way to present them, especially in conjunction with other materials. I can imagine that some instructors are doing a manual step of copying these figures onto slides.
• To present exercises, which are a key element of many workshops. This relates to Feature request: Exercises view/export #18. I think some instructors are presenting these using the materials website which isn't really designed for presenting.
• To share other formative assessment such as MCQs
• To define terminology for visual learners
• To signpost changes in episode to provide structure to the lesson

Considering this, and considering that pandoc (which powers RMarkdown) can readily generate slides in a few different formats, I wonder if there is interest in adding a slide export feature which pulls out these key elements.

One way it might work is by pulling out blocks of interest from the lesson using Pandoc filters, such as figures, exercises etc, and converting them to a slide format.

[zkamvar]

The concept of having auto-extraction of slides is not necessarily a new concept in The Carpentries. (see carpentries/styles#113 and swcarpentry/DEPRECATED-lesson-template#13). For what its worth, there is space in the page design for a button to download slides from an episode and we have a mechanism for extracting and manipulating content from the lesson in {pegboard} before it even gets to pandoc. That being said, I will manage expectations and say that this is not a feature that we can confidently implement before 2024 and there is currently no priority to do so based on the challenges below.

Scope

The problem is not that they are discouraged (as @tobyhodges pointed out in an earlier slack thread), but rather the problem is scope: what to include in the slides is one of those sticky situations where there is no one right answer (akin to the "lumper" vs "splitter" arguments of evolutionary biologists). This conflict arises from the fact that there is no 1:1 translation between lesson content and slide content purely because effectively writing slides is approached from a different persepctive as prose (the lessons are indended to be companion reference material for the instructors and learners, and are not necessarily intended to be presented during live instruction).

Capacity

There is the secondary problem of capacity: Our funders have decided that it was no longer possible to retain a position dedicated to development of the lesson infrastructure and the maintainers are focussed on bugfixes only. Right now, the maintainers (@froggleston, @ErinBecker, and @klbarnes20) are focussed on understanding exactly what capacity they will have to implement bugfixes and approve features once I am no longer employed by The Carpentries.

Capability

We have the capability to isolate elements of interest in {pegboard} (though it's not well documented: https://carpentries.github.io/pegboard/dev/reference/isolate_elements.html), which is currently used to generate code handouts that contain code and text from the challenges (without solutions). When we can come up with a salient way of allowing lesson authors to specify what should be included in the slides, but the next challenge is how to format the slides in a way that allows the content to all fit?

[multimeric]

Hi, thanks for this detailed response. I discussed this with a colleague today, and I think we concluded that it would be fine to just have an HTML class that designates slide content. For example, a challenge block that should also generate a corresponding slide might be:

::: {.challenge .slide}

:::

Since it will be a class, this could apply to any content or enclose any content, including figures etc, but authors would be discouraged from putting large blocks of text there. A possible future extension which is not part of the MVP might be to add slide only content which doesn't show up on the main notes. In my view this meaningfully addresses scope. "What to include in the slides"? Whatever the author specifies!
(as an aside, this class-based mechanism is standard pandoc stuff, so will be compatible when/if workbench becomes Quarto powered)

In terms of capacity, I totally understand the challenges there, but if we can hash out the details here, either I or some other contributor with time might be able to provide the implementation, if not one of the regular maintainers.

the next challenge is how to format the slides in a way that allows the content to all fit?

I would keep this out of scope for the moment. Let's just assume that it's the author's responsibility to tag only elements that fit on a slide as being .slide. Later on we could consider extensions like a .slide-shrink that shrinks the content down automatically to fit on the slide, or perhaps a mechanism for specifying manual font size.

[zkamvar]

In terms of capacity, I totally understand the challenges there, but if we can hash out the details here, either I or some other contributor with time might be able to provide the implementation, if not one of the regular maintainers.

I will bring this to the maintainer team, but you must be patient. Implementation is really only part of the equation. The vast majority of the work in adding a new feature comes with audience consideration, design, unit testing, integration testing, user testing, reiteration, release, and continued maintenance. All of this is very difficult to hash out over a single issue opened in the middle of Q4.

I have been working on a workbench developer's guide that includes a yet unfinished section on adding new features that may be helpful with guiding questions: https://carpentries.github.io/workbench-dev/features.html

[multimeric]

Thanks, let me know how and when I can help with any of that process.

[multimeric]

Hi @zkamvar, were you able to discuss this with the maintainer team?

[zkamvar]

I am no longer responsible for this product. Please direct your questions to either @ErinBecker or @froggleston.

[ErinBecker]

Hi @multimeric - @froggleston and myself have taken on maintenance of the Workbench as of January. Due to reduced capacity of The Carpentries Core Team, our focus this year is on maintenance and sustainability, which leaves little room for the development of new features. We're currently working through some backlog and have not had an opportunity to discuss this proposal.

[multimeric]

Hi Erin, this is totally understood. Just noting that I'm willing to implement (and maintain) this feature, so all I ask for is internal discussion and approval of the feature.

[joelnitta]

+1 to this feature request. I am willing to help @multimeric implement / maintain this. I know capacity of the core team is reduced right now. IMHO that is all the more reason members of the community should step up to help 🙂

[multimeric]

Some other details inspired by discussion in this thread:

• We can use pandoc's ::: notes element to support speaker notes: https://pandoc.org/chunkedhtml-demo/10.5-speaker-notes.html
• We will have to have an "auto" mode for the slide generator that works with lessons that weren't created with slides in mind, and therefore includes the default elements I listed above (challenges, images, titles etc). This can probably be specified in the config.yml.
• We can then add a slide-aware mode lessons that have been appropriately tagged. This behaviour will be to include nothing in the slides by default unless they're tagged with ::: slide-only (which will hide it from the materials) or ::: slide-also (which keeps it in the materials)

[svenvanderburg]

I like this idea, but I would prefer embedding the slides in the lesson material itself. Such as in scikit-learn's machine learning course: https://inria.github.io/scikit-learn-mooc/ml_concepts/slides.html .

At the Netherlands eScience Center we teach 20+ carpentries (style) workshops per year and contribute to 10+ carpentries lessons. We are moving towards having markdown-based slides in a central repository using NEBULA. So at least we have an easy way to keep 'our' slides up to date with lesson material and can easily share it with the world. But this is not the ideal solution.

I can say that especially with more advanced lessons like https://github.com/carpentries-incubator/python-intermediate-development/ or https://github.com/carpentries-incubator/deep-learning-intro slides are a necessity.

[svenvanderburg]

Follow-up on #78 (comment) : Here is an example slidedeck that we developed for our 'Good practices for Research Software development' lesson using NEBULA

(You can see heavy borrowing from CodeRefinery)

Would there be interest in having something like this for Carpentries (it would be quite easy to change the theme). This would be a temporary solution until this is embedded in the workbench.

[multimeric]

I like this idea, but I would prefer embedding the slides in the lesson material itself. Such as in scikit-learn's machine learning course: https://inria.github.io/scikit-learn-mooc/ml_concepts/slides.html .

This would be good in that future users will be able to see the slides alongside the material, but I'm concerned that actually presenting embedded slides will be cluttered compared to having separate slides.

Follow-up on #78 (comment) : Here is an example slidedeck that we developed for our 'Good practices for Research Software development' lesson using NEBULA

Unfortunately your link doesn't seem to work?

I can tell that there's a lot of community interest in this, but I'm holding off until we hear from the Carpentries maintainers. Unfortunately they don't seem to be prioritising this feature.

[froggleston]

I'm afraid our answer will be the same - this is not a priority for us in the Core Team to support and maintain in the Workbench currently. There are a lot of implementation questions, as well as issues with content selection for generating slides, not to mention maintenance of not only the embedding but updating slide content when markdown content changes.

I'm afraid we won't be able to commit to this in the short or medium term.

[multimeric]

Well I would be happy to help discuss and implement this when it becomes prioritised.

If other instructors are interested in a short term solution, I've developed a separate slide generator: https://wehi-education.github.io/CarpentriesSlides/. This is of course not as ideal as a Workbench-integrated generator but it has been quite beneficial for workshops I have run. Generally I use as the basis for my slides and then make a few tweaks manually.

[svenvanderburg]

Well I would be happy to help discuss and implement this when it becomes prioritised.

If other instructors are interested in a short term solution, I've developed a separate slide generator: https://wehi-education.github.io/CarpentriesSlides/. This is of course not as ideal as a Workbench-integrated generator but it has been quite beneficial for workshops I have run. Generally I use as the basis for my slides and then make a few tweaks manually.

This is great! Thanks for sharing ❤️ Do you have an example running somewhere?

[svenvanderburg]

I like how Scikit-learn's introduction to machine learning embeds slides and videos.

Agree that there is a lot of interest from the community. You can see from these notes on a discussion on training at the intermediate level that took place this week during CarpentryConnect Heidelberg that slides are important.

@froggleston at the same time I agree we should not implement this in the workbench when capacity is so low.