Feedback General Feedback, missing functionality and bugs

Hi!

I tried the IET framework a while back (after seeing it in the LEGO tutorials) and also tried creating custom tutorials, and was impressed at both the complexity of the custom inspectors and the "hackiness" in place to inject in all kinds of places in the editor . I personally think especially the experience for tutorial creators is not ready for a public release, but since you seem to think otherwise I'll just list some feedback and bug reports here:

1. Seems there is currently no way to highlight menu items or point people to where to open them. Is the recommended approach here just to write this in plain text "Open Window > Custom Thing" and have a EditorWindowCriterion for completion? (Case 1320855)

2. From a UX standpoint, for masking you really need a way to "pick", maybe that can be done in a similar way as the UI Debugger does. It's really cumbersome to figure out what is needed here. It's somewhat easier with source access/good decompilers (e.g. Rider)

3. The way masking works seems very hacky (separate "mask" and "outline" objects?) and breaks in simple cases already (e.g. undocking a window) - (Case 1320860) - where the mask area and the outline affect different places in the window, which breaks the tutorial for users.



4. There's still a ton of testing code in there, e.g. the "Force default inspector" checkbox, is that really intended?

5. It's very confusing that all paragraphs have a "Masking Enabled" checkbox and it's not clear why that is. Seems only the masking from the first paragraph is ever used?

6. It seems that adding criterions is broken in 2021.2, seems to work in 2020.2 (Case 1320883)

7. When no scene asset is set for a tutorial, a new scene will be created instead of staying in the current user scene. Is this intended? Imagine a tutorial that explains you how to create specific types of objects for your scene, or uses some analysis tools in it.

8. Selection criteria are broken when the object reference is a child in the hierarchy; additionally, going "Next" then "Back" on a selection criterion breaks the tutorial (tutorial window is masked, user can't progress anymore). (Case 1320889)

9. It seems that VisualElements (renamed: UI Toolkit) isn't supported for masking - is that an oversight? Will that come? Or am I missing something... This feels weird as Unity has been advocating for moving editor UIs to VisualElements for a few years now (and some of Unity's UIs have already moved over, e.g. Settings and PackageManager). Doesn't look like one can make tutorials for them now. Good test case: Make a tutorial page that asks the user to select a specific package in PackMan and install it.

10. In general, I think you should "dogfood" this more in actual usecases besides the beginner-friendly workflows in e.g. the Microgames. How about you make an In-Editor Tutorial for tutorial creators, that shows people how creating tutorials work?

11. It would be great to have a slight delay between "criterion is completed" and "tutorial jumps to the next page", otherwise it feels like the user has done something wrong ("huh - why did the page switch now? I haven't clicked Done yet!"). Auto-advancing in itself is useful but having a slight delay of say 1s would make it less confusing.

Looking forward to feedback to the above - hope that helps! I really look forward to more in-editor tutorials
Thanks,
Felix

 

I'm on 2.0.0-pre.4, I think I tried 1.2.X in the LEGO tutorials but for the tests above I used the latest.

2. For IMGUI there's a separate debugger under Window > Analysis > IMGUI Debugger that can pick IMGUI elements:


4. Would be great if you move it to a less-obvious place - right now it's the first button when someone opens a tutorial page; Unity-style candidate would be the ⋮ (three dots vertical) menu in the top right of each window:
I understand it's an emergency option and very useful, I just think it's not good to have a "pre-release" or even "verified" version that needs the emergency button in such an obvious place.

5. Would be great if you change the UI to reflect that this only makes sense for the first (e.g. hide the masking toggle from the other elements when the default inspector is active) – otherwise it's pretty confusing and far too easy to put stuff in wrong places and then wonder why it doesn't work. I'm also wondering if I'm allowed to change that structure (3 paragraphs) or if everything will break then; right now it looks like I can?

7. Yes, please, as outlined - let me know if you need additional info as to what the usecase for that is. Right now it seems "tool tutorials" would always need a special scene and I can't tell people how a tool works in their scene even with careful crafting of conditions etc.

8. I'm not sure I understand that. Users certainly have a need to go a step back if they feel they didn't understand something or want to take another look. In the case I outlined (and reported as bug) it actually breaks the tutorial because the condition can't be fulfilled anymore since the marking is incorrect and doesn't allow me to click on the right object.

9. I think you should really prioritize this; otherwise this becomes another case of Unity releasing X New Things that only work with Old Things and not with each other, really hindering adoption (e.g. we try to use and give feedback to the combination of new things since that is relevant for the future, not how a New Thing works with Old Things individually).

10. Yes, I meant that you could try creating a tutorial for the tutorial creation. As mentioned I think that the "template tutorials" shipping with Unity now or in the future are all pretty low complexity (they are meant for beginners after all) and I see the value for end-user tutorial creation in much more complex flows. Thus, if you can make a tutorial for how to make tutorials that would certainly help to prove that complex workflows can be "tutorialized".

Thanks for listening,
Felix

 

Hi Paolo,

We're really excited to see the Tutorial Framework eke its way towards release, and are in the process of translating some teaching materials to it for testing purposes.

In one of your responses above you said:

Yes, only the masking of the first paragraph is used. This is the same set of masking settings the inspector displays (unless you check "force default inspector").
The system previously allowed to set different masking settings and multiple instances of the same type of paragraphs (I.E: multiple instructive paragraphs) per page, but over time we realized that we wanted to simplify the structure of tutorial pages so they have only one instance per type of paragraph, top.​

I feel that last part of this is a poor choice, or at least limits the flexibility of the Tutorial Framework. For example, I would like to make a really simple beginner's tutorial that advises e.g.:

• Create a new empty GameObject
  
• Call the GameObject "MyFirstGameObject"
• Add a new Script called "FooScript" to the "MyFirstGameObject"

Each of these steps are simple enough, but I'd like to present them on one page, rather than end up with a tutorial that is 100s of pages long because steps like this must be split up if you want to be able to easily show the learner which part of the process they've got wrong.

Ideally for my use case, this kind of thing would have multiple instructions on a single tutorial page.

Any chance of allowing what appears to be the old/original functionality to be used?

 

Thanks for the response Ali I'll hope for 2.0

 

[Apologies if this kind of post isn't helpful -- happy to delete]

We decided we couldn't wait and implemented this ourselves (multiple instructions and multiple narrative intermingled however you like):


I have to say it really improves the flow of the kinds of tutorials we are trying to create. So it'd be great if your discussions do end up in the return of this functionality for everyone. Looks nifty too with your good clean UI design

Also, we implemented a couple of other features we think are pretty necessary for certain classes of tutorial:


Left: unlocking progression (i.e. tutorials with pre-requesites). It's likely to be helpful to allow for a multi-part tutorial with each section requiring the previous to be completed. In the picture: section 1 & 2 are complete, section 3 is unlocked (as section 2 is complete), and section 4 is locked (as section 3 is not complete).

Right: code blocks as part of the rich-text support. Our implementation of this has them be selectable too, so things can be copied into the code editor. An even better version would also provide automatic syntax highlighting also. (Not pictured: inline code sections too, so we can mix normal text and highlight code parts).

Any chance that these are features you might implement in the future?

 

Hi Paolo,

Only a short answer here, more to follow when I have a bit more time:
- We used a bit of both, but mostly this relied on our own version of the package. It wasn't really possible to allow for multiple "paragraphs" per tutorial page otherwise we don't think. Would be super happy to chat about how we may have been able to accomplish more of what we did through the API directly (we were rushing, so may have missed some opportunities there).
- Very happy to share the code, would like to help the whole community in this endeavour What's the best approach there?

Cheers,
Ian

 

@giant_ian you could make a fork of https://github.com/needle-mirror/com.unity.learn.iet-framework.authoring and add your changes in the fork, then paste the link here - this way it's clear what version of the package it's based on, there's a clear update path etc.

 

@PaoloAbela I've sent you a ZIP of all our stuff and the example tutorials we've made with it
@fherbst Alas, I am git-phobic :/ (in the minority I know, but we use SVN for all our projects)

 

We implemented some other things before trialing IET with our students. Informal feedback so far is they thought IET was far superior to text tutorials with screenshots or even a video version of the same content (we provided all three).



Left: We added hyperlinks the reference Assets (left image, with the mouse hovering over the "BasicSpawner" link)

Right: Also hyperlinks to GameObjects in the current open Scene (right image, with the mouse hovering over the "Spawner" link).

Selecting these hyperlinks highlights the asset/gameobject with PingObject.




Left: we added a new form of completion criteria "Completed on User Indication". Users tick this box to mark the Instruction as complete. (Perhaps this should've been done with a custom Criteria rather than an addition to the Instruction Paragraph, but I'm not sure how we would've got the checkbox then).

(Also Left: in-line code blocks).

Right: Poll Paragraphs. Selecting any option marks the Paragraph as complete, and users are shown whether the answer they selected is correct (and if not, the correct answer is shown) -- here I selected the wrong answer. These Polls are meant as quizzes, just to test the user's understanding of the concepts.

 

Adding those features was a pretty exciting side-project.

The in-line links to assets and gameobjects take very little to support, and really helps with student comprehension of directions, and means you don't have to write complicated directions to stuff deep in folders too. If they can't find something themselves, or are confused about exactly which thing you are referring to, it's just a click away

We'd love to have added similar links to things in the inspector too: components (e.g. SpriteRenderer) and fields (e.g. Transform's Rotation) and sub-fields (e.g. Transform's Rotation's Z value). But alas the Highlighter class seems to have fallen into disrepair (perhaps connected to old UI versus new UI changes?). It'd be great if an update / replacement for that could be part of the IET package.

 

@RikuTheFuffs-U got more feedback about the workflow, and possibly more bugs...

1) In some cases, it seems the strings are not editable, not sure why:


2) We've tried out our tutorials internally, and some people (not all) have reported that tutorial exit / closing doesn't work and instead opens the Unity Hub - was able to get a recording:

This is a serious bug as the only way to get out of that loop is to kill Unity via Task Manager. Not sure how to reproduce though (on a different machine it worked), on the affected machines it happens every time (persists after restart).



EDIT: I was able to isolate the issue and reported as (Case 1332108) [IET] Tutorial workflow is broken, skips steps, can't be closed anymore.

3) The same issue I reported as bug before "(Case 1320889) [IET] Masking objects does not mask correct regions after going backwards in the Tutorial steps" was also brought up by many as a bug, and in fact breaks the tutorial flow entirely in some cases. I can see that the issue was "closed" but I have no idea why, and I still believe this is a bug.

Here's a simple flow that breaks with this:
- Tutorial asks to select Object A (Object A is masked)
- Tutorial asks to click a button in a window to export Object A; the button is masked (only the button can be clicked)
- Tutorial reaches last step. The user clicks around a bit (no masking), and selects Main Camera. Now, they want to repeat some of those steps, so they click Back, and Back again.
- Tutorial asks to select Object A (no Masking) but marks the step as done
- User clicks "Next"
- Tutorial asks to click a button to export Object A; only that button is available. Note that currently Main Camera is selected, not Object A, and the user has no way to correct this. Clicking Export will result in a wrong state and wrong result for the rest of the tutorial.

For users, these two actions are identical:
- restarting the tutorial
- clicking back until they arrive at the first step again

 

Case 1332108 is on
Unity 2020.3.4f1, IET 1.2.3.
I just updated to 2.0.0-pre.4, and the "Hub Opens" issue is indeed gone - great!, the other issues outlined in that case still remain. But I can confirm that in 1.2.3 the Hub opens even with users logged in (everyone who tried this was logged in properly).

For the rest that I wrote, I was already on 2.0.0-pre.4 and Authoring 1.0.0-pre.4.

As outlined in Case 1320889, the current behaviour with going back is very broken, as it results in masked windows but the steps can't be completed or are incorrectly completed automatically. The callbacks would work, yes, but also might increase the amount of work for creating tutorials to a point where I don't think it's desired anymore - if the Completion Criterion isn't really enforcing the criterion after that step I'm not sure what the point is. Ultimately that seems to mean writing additional "Completion Enforcement" scripts for each criterion etc.

Regarding Issue 1), I can confirm that I'm NOT running the tutorial when that happens. Also, it doesn't seem to matter if I have the "Tutorials" window open or not, editing is simply not possible anymore.
I also pressed "Clear all statuses" and restarted the editor a couple of times; still, I can only edit some text fields (e.g. the "Next" and "Previous" button labels) but not others (e.g. instructions/descriptions). It does seem to indeed be related to having criteria on those steps.

 

I've also encountered the issue where strings are not editable. I sent in a bug report this morning, though I do not have it on hand to get the reference number.(EDIT: Case 1332176)

Looking into it further after submitting my report, I noticed that the method I was referencing for an Arbitrary Criterion was running all the time (in the form of a debug.log statement), even when the tutorial is not active. This could be related, though I tried removing the Criterion and it didn't solve the issue. I'll be testing it further later tonight to see if I can replicate the string issues reliably.

EDIT: I loaded up Unity during some down time at work. In a new project:
Unity version 2021.1.4f1
Tutorial Authoring Tools 1.00-pre.4
Tutorial Framework 2.0.0-pre.4

Adding in any completion criteria at all disables text editing (even the default None).
This is confirmed by removing all criteria from the list (selecting them and subtracting from the list) and functionality is restored again to the text fields.