RFC - Interactive Tutorials

[cgalvan]

Summary:

The goal of this proposal is to bring support for Interactive Tutorials to O3DE. This will provide an additional avenue for users to learn how to use the engine and its tools. The framework would allow for users to discover tutorials on features/workflows, and also create their own tutorials for the benefit of the whole community.

A prototype has been iterated on in a personal public repository here:

https://github.com/cgalvan/InteractiveTutorials

What is the relevance of this feature?

There are some areas of the engine that can have a steep learning curve. Interactive Tutorials would serve as a complement to our online documentation (https://www.o3de.org/docs/) and video tutorials. The tutorials could cover everything from beginner concepts to advanced workflows, so they would be useful to any user regardless of skill level.

Feature design description:

Interactive Tutorials support is provided through a Gem. The Gem registers a simple tool which gives the user a list of available tutorials, and then guides them through the tutorial steps once one is started.

• The initial display of the tool presents the user with a list of all available tutorials
• Each tutorial is made up of a list of steps
• A tutorial step is made up of several parts
  • Title and content
  • An optional highlight pattern that will highlight a widget or item in the Editor for the duration of that step
  • Also has optional pre and post hooks that allow the user to add special handling/listeners to a specific step
    • e.g. blocking the user from proceeding until the next step until some action has been fulfilled, such as creating a new entity for use in the next step
• User is shown a display of which step they are currently on in the bottom of the tool
• Next/Back buttons allow the user to proceed through the tutorial at their own pace, and go back to a previous step if necessary
• Once the user completes a tutorial, they are taken back to the initial display of available tutorials to choose from

Technical design description:

The tool and tutorials are written in Python. This will allow quicker iterations and makes it accessible to a wider audience since Python is widely used for scripting purposes by artists and non-technical content creators across multiple DCC tools.

The framework is lightweight and consists of only a few classes:

TutorialStep

• The simple properties of the step are the title and the content
  • The content can be simple plain text, or also supports HTML and markdown
• The optional highlight for the step can be specified via a highlight pattern or parent/index combination
  • These make use of helper methods in https://github.com/o3de/o3de/blob/development/Gems/QtForPython/Editor/Scripts/pyside_utils.py that we use for our automated testing and other Editor scripting
  • Please see the documentation for “pyside_utils.find_child_by_pattern” and “pyside_utils.find_child_by_hierarchy” in the above module for more details on the robust API that gives us the ability to make both simple queries and very complex patterns
• Also optional “on_step_start” and “on_step_end” that gives the user the ability to attach any custom logic to the beginning of a step, or any cleanup that might need to be done after

Tutorial

• This class contains a list of “TutorialStep”s as well as a title for the tutorial itself
• It also has optional “on_tutorial_start” and “on_tutorial_end” to setup any custom handling/listeners the user might want executing while the tutorial is in progress

InteractiveTutorialsDialog

• This is the dialog for the tool itself that gets registered as a dockable tool in the Editor
• It is in charge of displaying a list of registered tutorials to the user
• Once a tutorial is selected, it loads the “Tutorial”
• As the user navigates through the tutorial, it displays the appropriate title/content data from the “TutorialStep”
• It also invokes the “on_step_start”/“on_step_end” custom method hooks on each step

What are the advantages of the feature?

This feature provides an interactive experience to help our users learn how to use the Editor and tools. It also empowers our users to create their own tutorials to share with the community.

• Allow beginner users to easily discover basic workflows/tools while in the actual Editor itself
  • Visually guide users step-by-step through workflows that bounce between multiple tools in the Editor
• Breakdown more complex workflows through a guided workflow
• Interactive tutorials are easier to follow since they don't require users to multi-task between different applications to follow along
  • They would also highlight elements of the interface, which makes the learning process easier (especially if the Editor layout is different than the one in the tutorial video/images)
• Help users discover new features + how to use them
  • Hands on practical experience reinforces learning concepts
• Allow users to create their own interactive tutorials with an easy to use framework
  • Provided that the API is stable enough, interactive tutorials are less prone to becoming outdated, since they would still point at the correct UI elements even if they are moved around in the Editor, and it should also be easier to keep them up to date since an automated test can be setup to verify when a code change would break parts of the interactive tutorial

The documentation team has been involved in the development of this feature and has found that it enables writers to provide tutorials much more quickly than through the traditional documentation process.

• Creating interactive tutorials forces writers to be concise due to the constraints of the framework.
• The interactive nature reduces the need to create and maintain example figures and movies for every tutorial.
• Interactive tutorials are much easier to test and ensure they remain relevant and updated as O3DE evolves over releases.
• Using an Interactive Tutorial first process for tutorial creation offers opportunities to automate content generation for website and video tutorials.

How will this be implemented or integrated into the O3DE environment?

The short-term goal would be to move the https://github.com/cgalvan/InteractiveTutorials Gem out of its separate repository and into the O3DE repository. There would first need to be a minor amount of cleanup before bringing it over.

How will users learn this feature?

• To help users discover the Interactive Tutorials, a link to open the tool could be added to the Help menu
• There is also a talk scheduled for O3DCon to introduce users to it and teach them how to create their own tutorials using it: https://o3dcon2022.sched.com/event/1AOaI/crafting-interactive-tutorials-for-new-and-advanced-workflows-christopher-galvan-aws?iframe=yes&w=100%&sidebar=yes&bg=no

Are there any open questions?

1. Currently the tutorials are registered manually in the Interactive Tutorials Gem itself. It would be ideal to instead have a registration system that would allow users to register tutorials from their own Gems. That way, those tutorials would only be visible if the corresponding Gems were enabled.
   1. For the many use-cases of tutorials that would come with a Gem, it would make sense for them to only be shown if the Gem is enabled. However there are likely some edge-cases for common or important workflows that come in Gems that aren’t enabled by default. So to handle this we could have those tutorials registered in the Interactive Tutorials Gem itself, but then have a way of marking them as dependent on other Gem(s), and if they aren’t enabled for the current project then they would be disabled in the list and would indicate to the user that those Gem(s) would need to be enabled for the tutorial to be functional.
2. We could potentially allow the user to view the whole index of all the steps and to jump to a step in-between. If we did this, we would need to build in mechanisms to have blocking requirements (e.g. if you skip to a step that adds a component on an Entity, you would need to make sure that Entity was created first)

[tkothadev]

very cool idea. Do you know if it would be possible to turn the manual portion of the interactive tutorial into a gem that others can use for their own documentation?

I could see others having manuals dedicated to describing their own gems (especially if it's a complex component)

[cgalvan]

very cool idea. Do you know if it would be possible to turn the manual portion of the interactive tutorial into a gem that others can use for their own documentation?

I could see others having manuals dedicated to describing their own gems (especially if it's a complex component)

I believe so, are you referring to the manual steps/content of a tutorial? If so, then yes. The content itself does support simple markdown format, so you could re-use that directly into something like GitHub wiki pages.

[cgalvan]

We had a great discussion about Interactive Tutorials during the sig-ui-ux meeting on Discord last week. Some of the ideas that came out of that discussion were:

• Chaining multiple tutorials together to allow for shorter tutorials that achieve a larger goal, instead of having one single long tutorial
• Make the Interactive Tools dialog semi-transparent so it could be floating above the Editor and still be able to see the Editor tools behind it
• Improved discoverability (e.g. search filtering of content, or launched directly from asset toolbox)
• Give users the ability to skip steps

[monroegm]

At SIG-Content Triage on Wednesday, October 26, 2022, we decided to initiate the final comment period for this RFC. Please submit all remaining feedback by Monday, October 31, 2022.

[lmbr-pip]

Is the proposal that the Gem is owned by SIG/content? If so do we have automation plans for gem?

Who owns the individual interactive tutorials? Is this cross-cutting with SIG/docs-community? Do the tutorials live individual gems?

Can we clarify expectations for ownership?

[monroegm]

Approved at SIG-Content Triage on Wednesday, November 2, 2022. Please commit this RFC to the repo.