Explore technologies available for User Guidance

[IanMayo]

🐞 Overview

This is a research task, to explore technologies that could be used to deliver engaging guidance and instruction to analysts.

As Feature #595 details, we need to educate analysts across a range of subject areas, from abstract subjects such as "platform uniqueness constraints" through to the detail of running import and admin.

I guess we can interpret "engaging" in a number of ways:

• learning is interactive - so students do more than click "next slide"
• students become comfortable with Pepys, by performing standard tasks using it (possibly real or simulated)
• use of illustrations to ease understanding
• Use of notebook widgets to do something

At first guess, these could be candidate technologies:

• PowerPoint
• YouTube video tutorials
• Online eLearning materials / Learning Management System
• Jupyter Notebooks [1]
• Jupyter Notebooks rendered as RISE slideshows

Or, the guidance provided could be a combination of the above, though that seems sub-optimal from a usability perspective

But, the suitability of a technology has other constraints:

• Can run on analyst "office" network (with Internet connection, but unable to run Python)
• Can run on analyst "analysis" network (without Internet connection, but able to run Python)
• Can be authored by @clenoble [2]

[1] The advantage of the Jupyter notebook is that "students" can run live instances of Pepys-Import and Pepys-Admin [2] This may require training/guidance too, or effort from @robintw in providing some test-case examples.

🔗 Feature

Supports #595 - Improved User Guidance

🔢 Acceptance criteria

[IanMayo]

@robintw - I think it may prove useful to establish if it is possible to run an XTerm pepys session in RISE.

A positive aspect of RISE seems to be the slide-based nature. It's one nugget of information at a time for the user to focus on, rather than a long document.

[IanMayo]

Update We chatted this morning. @robintw reported that it would be challenging to provide training content and an XTerm interactive Pepys on the same RISE slide.

We also identified that running Pepys in a RISE slide loses a bit of context - it isn't triggered from the Send to > menu. Doing this in MS-Windows (or at least viewing a video of that happening) would make sure the analyst/student is familiar with how to start the import process.

Also, we identified that the Binder-hosted version of Pepys made it available to a new analyst from any Internet connected terminal/device - and so is suitable for self-guided training either at home, or on a business PC that doesn't have Pepys installed.

We ended up with this strategy:

• Training session is lead from content in a slideshow
• At points where interaction is necessary, student can choose to either practice the step in a separate browser tab (poss as RISE slide), or to follow the step in MS-Windows.
• The student should be made aware of when to come back to training content & potentially be given more background guidance.

[IanMayo]

@clenoble discussed giving a visual illustration of data going into Pepys, based on a view of the tables. We don’t know the eventual technology we’ll be using, but here’s one way of doing it.

1. Use a series of G-Slides slides to show the changes. The schema diagram could be repeatedly copy/pasted with changes being added to each successive copy
2. I could then play the presentation, and use my copy of Gyazo Pro to capture it as an animated GIF.
3. This animated GIF is then usable across lots of possible technologies.

[clenoble]

@IanMayo Rather than Google slides, I thought making an interactive prototype in Figma would work best. With an animated GIF, we need to make it slow enough for users to follow. Is there the possibility to pause and re-start in a GIF?

[IanMayo]

@clenoble - if we can avoid Figma for the user guidance, I'd like to, please. I don't think we would have a way of the content being viewable on the network without an Internet connection. It also limits the participation to you, mostly.

If you want to mockup in Figma and record that to video (or gif) then that wouldn't be too bad, but it wouldn't be interactive then. Is it worth us chatting through what the interactive prototype would look like?

With an animated GIF, it replays at the speed it was recorded at - so that's how the speed is controlled. Clicking on the animation pauses/restarts it in most browsers (& ppt, I think).

[IanMayo]

The current version of the presentation is being developed in Google Slides - so it's easy for distributed working.

In the longer term, this format/technology may bring this/these challenges:

• Google slides not accessible from users' analysis (air-gapped) network
• Google slides not accessible for users' office (locked down) network

Exporting to MS PPT would overcome the above issues. But, going to MS PPT means user/student must have access to PowerPoint. Note: it may be possible to use Google Slides to view MS PPT without having PPT installed.

An alternative is to export to PDF, though I think that will prevent the ability to do slide builds.

Another option is to use an HTML slideshow. I don't think it's possible to export Google Slides or PPT to the markdown/native formats these technologies tend to use. But, I'm happy to fund a suitable expert to do an initial translation. If we did have the training guidance in Markdown format, a GitHub action exists to convert it to a number different HTML slideshow technologies: https://pandoc.org/installing.html#github-actions