Walkthroughs

[arvind]

With a history stack (#236), we should be able to turn any visualization into an interactive tutorial/walkthrough. A simple UI/mechanism to be able to do this would be very powerful, and could spur adoption. The resultant tutorials should likely include little popovers w/explanatory text (ala Shepherd/Tour.js and #239), as well as yellow-fades for intermediary steps where such text is unnecessary.

[deathbearbrown]

Using the history

To create a history based walkthrough, we would need to set an initial state in redux to go through "undo" for each step. Luckily they have that option in the redux package kadam did his undo/redo proof of concept with. https://github.com/omnidan/redux-undo#initial-state-and-history

But we will have to generate that state map for a visualization, it wouldn't like you could just pass a vega spec to the app and create a tutorial mode.

To use the pop overs, I think it gets a little more complicated because we would need to include which step we are on in each of the past actions we are running through.

I think the technical bits will get worked out once the refactor kadam is doing right now are settled.

Discussion

1. what if a person goes off course and starts modifying things and blowing away the history?
   • Potential solution: We can put "tutorial mode" on where a user can't interact with the app until they are ready to dismiss the tutorial and start playing
2. Watching an app run through a task is not as good a learning mechanism as doing.
   • Potential solution:

I would suggest building walkthroughs out as steps that need to get validated before going to next. This would mean we don't need to rely on the redux history, but we'd have to create additional validation functionality. I drew this out in my notebook to explain: We would generate a step by step tutorial with animated gifs that would populate the hints popup right below the visualization. The user would have to do each step, hit next, then it would validate if they did it correctly by validating the canvas with an image. I think you used to be running the unit tests against images for lyra2.

They also use this on the site Udacity for 3D graphics quizzes. I'd link but you have to sign up to see it. :/

[deathbearbrown]

After talking with Kadam about the work he's doing with redux, I think I know what I'd like to propose.

Walkthroughs would be stored in the app as JSON objects. The structure will look like this:

{
    "walkthroughName": [{
        "id": 1,
        "title": "Step 1: Add a mark",
        "text": "Click on the RECT button in the toolbar to add a new Rect to the canvas",
        "image": "url to gif thumbnail",
        "lyra-state": {}
    }, {
        "id": 2,
        "title": "Step 2: Change color",
        "text": "Select the new mark and then change it's color to #bbCCaa in the property inspector",
        "image": "url to gif thumbnail",
        "lyra-state": {}
    }]
}

Properties:

id - the order in which the steps will be preformed. title - title text for the hint menu text - description of the action you want the user to preform image - animated gif of the interaction. e.g.- This could be showing the cursor dragging data onto a mark and the X,Y drop zones appearing lyra-state- this is the redux state that the current step should be initialized with

WALTHROUGH the walkthrough

• A box appears and it prompts the user to do the action.
• The user does the action and clicks NEXT
• NEXT checks the current state of the app against the 'lyra-state' object for the next step. If it does not match, there will be an error message. How detailed the error message is depends on how crazy we want to get with the validation code.
• If there is an error, an additional call to action will appear in the walkthrough box along side NEXT, which is FORCE CONTINUE (or a better name).
• If the validation passes or if the user chooses FORCE CONTINUE, the next step will begin by instantiating the 'lyra-state' for the next step as it's the current lyra state.
• That way a user never can veer off coarse, and continue with the walkthrough even if they get stuff.
• This will also make a user interact with the app instead of running through "redo" states in the history.

If we are cool with this interaction, this is how it will break down work-wise:

• Blocker: getting the rest of the app in the redux store.
  • Currently Kadam is working on Marks. Pipelines, scales and guides will also need to get into redux. BUT, once Marks is complete, it will define what that looks like for everything else.
• Create walkthrough react component with the following functionality:
  • dismiss
  • title, text, image. Next button, Back button, optional Force Next
• Create error message react component
• Create walkthrough utility
  • utility will populate the walkthrough react component
  • do the validation of the redux state
  • throw errors

[arvind]

@deathbearbrown, this looks great to me! I particularly like the validation against the lyra-state, so that users actually have to interact with the app to progress through the tutorial. Some comments/questions:

• Thoughts on specifically requiring the user to hit "next" to advance vs. automatically advancing the tutorial once we see they've done the right thing? The latter's probably harder to implement (with a negligible UX impact) but I wanted to make sure we'd considered it.
• "Force continue" (wording tbd) makes sense to allow users to recover part-way through a tutorial. But I also think we should allow users to only go part-way through a tutorial and then veer off into doing their own thing. So perhaps a "Quit" option should always be available somewhere (either the popovers or in the general UI) that allows a user to exit the tutorial but preserves their lyra-state?
• How would someone construct a tutorial? Could I take an undo/redo history stack and easily convert it to a lyra walkthrough data structure? Presumably users could also start part-way through a tutorial too.

[deathbearbrown]

• If we validated based on any action made to the scene, it might be annoying for the user to get error messages. Say they add a mark and then are like... oh let me play with this and add a symbol and a group, we don't want to throw error messages at them. If you have a next button, that's saying "I did the thing, I'm ready to keep going", if you give me an error now I see the cause and effect relationship.
• Definitely planning to have a quit option.
• to build them out it's going to require that we have exporting set up. For each step you need to export the lyra state. If you wanted to go super polished with this you could have an admin interface for creating the walkthroughs, but right now what you'd need to do is construct the json object by hand.

As long as there's an export utility that doesn't modify the lyra state, you can absolutely, go through the motions of making a chart, then undo each step and export as you go.

[deathbearbrown]

UPDATE: To build a walkthrough use this JSON object, which has changed a little from the initial one proprosed

{
  "title": "Cool times",
  "image": "https://placeholdit.imgix.net/~text?txtsize=33&txt=150%C3%97150&w=150&h=150",
  "alt_text": "an image",
  "steps": [{
    "id": 1,
    "title": "Step 1: Add a SYMBOL",
    "text": "Click on the SYMBOL button in the toolbar to add a new Rect to the canvas",
    "image": "http://fillmurray.com/g/150/150",
    "alt_text": "an image",
    "lyra_state": {}
  }, {
    "id": 2,
    "title": "Step 2: Change symbol shape",
    "text": "Select the SYMBOL and change it's SHAPE to CROSS",
    "image": "http://fillmurray.com/150/150",
    "alt_text": "an image",
    "lyra_state": {
      "marks": [{
        "type": "symbol"
      }]
    }
  }]

The title and image for the walkthrough is what is shown in the walkthrough picker.
The steps are what's shown during the walkthrough.

We validate against the exported vega json and what is listed in lyra_state for the next step.
It's very soft validation, in that it will only look to see if the required items exist. It will not error if additional items are there.

ADDITIONAL TODOS: Validation needs to be hooked up for Scales and Guides.