Generate slides from the workbench

multimeric commented 7 months ago

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 #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 commented 7 months ago

The concept of having auto-extraction of slides is not necessarily a new concept in The Carpentries. (see https://github.com/carpentries/styles/issues/113 and https://github.com/swcarpentry/DEPRECATED-lesson-template/pull/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 commented 7 months ago

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 commented 7 months ago

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 commented 7 months ago

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

multimeric commented 5 months ago

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

zkamvar commented 5 months ago

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

ErinBecker commented 4 months ago

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 commented 4 months ago

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 commented 1 month ago

+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 commented 1 month ago

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 commented 2 weeks ago

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.

carpentries / workbench