Create training collateral

[nrichers]

Internal Notes for Reviewers

This PR demonstrates a standard for our first training modules, with an eye towards solving an important piece of the training puzzle: how to enable hands-on training for our users.

Features:

• Interactive — it's instructional content combined with the live product.
• Easy to use — feels like a slide deck but you're learning about the product while using it.
• Flexible — From surfacing the live product, to running Jupyter notebook code right inside our training content, to having our full docs framework available, to fine-grained CSS control, there's a lot we can build with this.
• Single sourced — task steps are shared with our current docs via some single sourcing.
• Easy to author — with the exception of the CSS framework extension, we're simply recombining stuff we already have.

I want you to test this training module and tell me what you think. It's not perfect — the intent here is to improve on the static Google Slides we've been using and to pave the way for future refinements.

How can I try this?

Since we trialled an earlier version of this with some users, the training modules are already live:

• Training for Model Developers
• Training for Model Validators
• Training for Administrators

If you test locally: gh pr checkout 200

• The Tachyons CSS framework should be included, but if not: https://github.com/nareal/tachyons
• Also in this PR but not currently used, an extension for flyouts: https://github.com/schochastics/quarto-nutshell

Bugs, issues, known problems

These need to be fixed before merging:

• JupyterHub
  • Enable iframe embeds for JupyterHub (OR include rendered intro notebook in docs site as a reference)
  • OAuth cookie error → TRACKED VIA https://app.shortcut.com/validmind/story/4946/fix-oauth-error-in-jupyterhub-for-training-modules
  • Investigate TOC links issue
• Add Navigation hints to slides
• Add role prerequisites
• Turn off chalkboard to prevent Backspace weirdness
• Single sourcing
  • Fix single-sourced content step numbering
  • Remove “Edit or delete comments” from single source to simplify collaboration slide instructions
• Split users & permissions pages (recent UI change): → TRACKED VIA https://app.shortcut.com/validmind/story/4437/documentation-design-settings-permissions
  • Check if add roles has changed?
  • Check if manage permissions has changed
• Content blocks (recent UI change): → TRACKED VIA https://app.shortcut.com/validmind/story/4971
  • Update content block docs to match latest UI changes
  • Add edit content blocks section and include as tab in developer training module
• Update the training home page with direct learning track links and add administrator track
• Add a slide with more detail around the workflow prerequisites, e.g. explore the current workflow and then tell developers to look in the administrator training for the details on how to set it up. → TRACKED VIA https://app.shortcut.com/validmind/story/4972
• "One specific comment for Slide 12/28 on validator track: there needs to be more guidance around the term review." → TRACKED VIA https://app.shortcut.com/validmind/story/4973

External Release Notes

We're introducing the first training modules that will be part of our training program for model developers, validators, and administrators. Our training modules are interactive, combining instructional content with our live product, and are easy to use. Try it: Welcome to ValidMind Academy

[MichaelIngvarRoenning]

see newer comment.

[MichaelIngvarRoenning]

Suggested change

	- Start the model development process
	- Initialize the model development process

[nrichers]

@MichaelIngvarRoenning we can update this, but the current text essentially repeats what's in the introductory notebook for devs. If we change here, we should change there as well.

[MichaelIngvarRoenning]

Instead of Developer Framework can we use ValidMind library (don't change if we don't agree)

[nrichers]

I agree but we should make this change across all the content for consistency. This text currently lives in all our customer-facing notebooks.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
1 out of 2 committers have signed the CLA.

✅ nrichers
❌ MichaelIngvarRoenning
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
1 out of 2 committers have signed the CLA.

✅ nrichers
❌ MichaelIngvarRoenning
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[MichaelIngvarRoenning]

A few points:

• It took me quite some time to understand that each screen was interactive that I could click and scroll in the UI and on overall slides that had more information below the starting screen of the slide. Make it very clear that the user needs to interactively move around the slide.

• For both the developer and validator track we are using a ValidMind instance with a lot of models registered in the inventory. There are a lot of weird names, duplicates etc. and I suspect it's hard for a user to locate what the description is telling them to locate. We need a clean up of the model inventory or we need a "clean" instance.

• I think maybe we need to include an admin slide in Session 1 because workflows need to be set up and configured for a model before we can continue the documentation process. I feel like that is a more natural flow of things. Feel free to disagree of course.

• One specific comment for Slide 12/28 on validator track: there needs to be more guidance around the term review. When I go and click on the validation report for the model stated in description I see the standard report but how should they know what to actually do in the task, is it review model documentation (which is huge) or is it review the validation report template and just click through?

[nrichers]

• Make it very clear that the user needs to interactively move around the slide.

Good point, the slides were not explicit enough about interactivity. We now include a callout on the "In this module" page that tells people training is interactive and provides navigation hints.

We need a clean up of the model inventory or we need a "clean" instance.

That's the plan! We now have a training org that includes a smaller set of models, see the screenshot. Eventually, we will also have:

• Sample model documentation in progress that you can explore without having to run the developer framework first
• Sample validation report artefacts you can use, such as sample findings, links to evidence, etc.
• Sample reports for the future MRM governance training

Together, these things will provide a more realistic training environment that mimicks how you would use ValidMind in production.

I think maybe we need to include an admin slide in Session 1 because workflows need to be set up and configured for a model before we can continue the documentation process. I feel like that is a more natural flow of things.

For tomorrow, I will leave things as is but perhaps it would make sense to add a slide with more detail around the prerequisites, e.g. explore the current workflow and then tell developers to look in the administrator training for the details on how to set it up.

(For context, AFAIK devs can't configure the workflow themselves and workflow setup is a pretty big chunk of the training for administrators.)

One specific comment for Slide 12/28 on validator track: there needs to be more guidance around the term review.

That's a good point — we're short on guidance not just in the training but in the docs generally. I'll follow up with @juanmleng to see if I can pick his brain on what's entailed in the validator review.

[validbeck]

Global comments

• I like _revealjs_navigation.qmd... is there a way to somehow make this includes something users can expand again in case they forget the shortcut without needing to go all the way back to this slide?
• I see you already changed some of the "Jupyter Hubs" to JupyterHub – thank you!
• The bottom modules look MUCH better. I like the newer stacked look, very clean.

Training for model validators

Is this lil guy supposed to be transparent?

Training for model developers

In the "ValidMind Introduction for Model Developers" notebook, some of the tables are a bit wonky with the horizontal scroll. Any way we can use some of the white space to the left opened up by no sidenav? Is there a "full width" version we can toggle in Quarto? It looks like we can only set it at the site level, hmm...

Training for administrators

Nothing to fix here from a preliminary click-thru. 🎉

[nrichers]

• I like _revealjs_navigation.qmd... is there a way to somehow make this includes something users can expand again in case they forget the shortcut without needing to go all the way back to this slide?

AFAIK, no, but I've been toying with the idea of adding ? for keyboard shortcuts to all slides, just haven't done it yet.

Is this lil guy supposed to be transparent?

Good catch! Looks like some late-night copy pasta. Should be fixed in 519e0e6

In the "ValidMind Introduction for Model Developers" notebook, some of the tables are a bit wonky with the horizontal scroll.

The current setup is a workaround and I agree it has some issues with how the content is rendered. I hope to overlay the training right over JupyterHub when it's all said and done.

[validbeck]

AFAIK, no, but I've been toying with the idea of adding ? for keyboard shortcuts to all slides, just haven't done it yet.

This plugin looks promising: https://github.com/McShelby/reveal-helpbutton

Should be fixed in 519e0e6

🎉 Can confirm!

[nrichers]

This plugin looks promising: https://github.com/McShelby/reveal-helpbutton

I'm going to park this in a new story, but a couple of comments:

• We might not need a plugin at all, we can just add a help link with our own stuff
• Not all reveal.js plugins work in Quarto. In fact many don't — my one insight after two days of testing CSS framework options. What's listed on quarto.org are the safe ones, plus there are a few other ones floating around.

That said, I'm all for testing and tweaking, and improving the training MVP iteratively. If that's something you want to tinker with, just claim the story!

EDIT: https://app.shortcut.com/validmind/story/4959