Reduce the number of buttons within the tutorial and include an example of the stage

[nhinds2]

Whats the Problem?

• What is the task, goal, need, or opportunity this request would address?

This request would address the problem of feeling overwhelmed with the tutorial and getting lost in other buttons when starting the code. This request aims to mitigate the information overload with having too many buttons, as it can be easy for users to get stuck pressing buttons that are unfamiliar and not relevant to the current tutorial. In addition, the tutorial should show an example of what the stage should resemble for practice problems, so the user has a better grasp of what is expected from them.

With the existing tutorial, there can be points of confusion as the tutorial does not correspond with the prompt. For instance, the user is unfamiliar with the palette and is not introduced to what it does at the beginning of the tutorial. However, the user can still access the palette which can increase confusion. Additionally, the user does not need to create multiple files, therefore the learned doesn’t need the file name and add file option. Furthermore, the user does not know if their code on the stage resembles what the tutorial is asking them to do.

• What is the context or scenario in which they would experience it?

When users first start the tutorial, they may press a lot of buttons, which may help with experimentation but also can lead to the user being overwhelmed with concepts they are unfamiliar with, such as the palette and other functions. Additionally, a user may attempt a task in the tutorial but can remain unsure if they completed the task correctly. This is because they are not shown an example of what the stage should look like once the task is completed.

• Who is the group of people who would be in this situation?

Users who are first learning code and using the tutorial for the first time.

• What is it about the current design that makes the need above hard to satisfy?

The current design for the tutorials allows for many options, which can lead users astray from what the tutorial asks. While these options allow for experimentation for the coding, if a learner is first learning the program, they only need the stage and the relevant features to reduce distraction. A user may become overwhelmed if they are given buttons related to concepts that they have not been introduced to. Additionally, there is no example of the stage, which makes it hard for the user to know if they completed what the tutorial asks them to do.

What's the design idea?

The design idea is to add an example of what the stage should look like for each tutorial activity prompt. In addition, I propose solely including one file and reducing the number of buttons in the tutorial. The user doesn’t need to include multiple files for the beginning stage of the tutorial, therefore the number of files can be reduced. In addition, removing the palette button for users will mitigate confusion. Lastly, many buttons at the top haven’t been formally introduced in the tutorial. Due to this, I propose only including buttons relevant to the introductory stages of the tutorial.

Design specification

This design proposal shows an interface with solely buttons that are needed at the beginning stages of the tutorial.

For the project toolbar, I am suggesting to remove the "palette" and the “add file”/ "file name" buttons because the tutorial does not require multiple files. Thus, the project toolbar only needs the guide and the undo button. This is because, for the preliminary tutorials these buttons are not needed to reduce confusion. In addition, I limited the arrows within the stage, as for the first step in the tutorial, the user is only expected to do one action within the stage.

For the editor toolbar, I am proposing to only have the “undo/redo” button and “select neighbor before/after” buttons because it is the most intuitive for the user to use and labels are the most explanatory for the user. I am also planning to keep the minimize, full screen, and language and mouse and keyboard toggle, as they are also commonly used by users and do not need prior coding context to understand.

I am proposing to remove the rest of the buttons in the editor toolbar. This is because the editor toolbar is not introduced, therefore a user doesn’t have ample tutorial for using it. This eliminates the problem of a user becoming frustrated with knowing what the buttons in the editor toolbar do when they are just starting to use the tutorial. Once they are familiar with the code after they have completed the tutorial, they will have the proper context to use all of the buttons in the editor toolbar in the actual code workspace, which reduces the confusion.

Here is a close up of the proposed change to the editor toolbar: After the hidden functionalities are revealed, they will always stay available. This is because once the user has been familiarized with the functionality, they understand how it works and can recognize it in the coding workspace. Due to this, the hidden functionality would only be introduced once the tutorial introduces the functionality.

I propose adding an element to the tutorial giving an example of what the stage should look like when instructing a task. This gives the user of the tutorial an “end goal” for what the tutorial is trying to teach. By including a rendering of an example output of the stage, the learner gets a better idea of what the tutorial expects.

I propose to show a rendering of an example output on the stage. This would be shown only when the tutorial prompts the user to do a code task, so the user has a non-interactive screenshot of what the tutorial expects. My reasoning for this is showing a render of an example output would give the user a “match” for their expected output on their own stage.

[amyjko]

Thank you for the design proposal @nhinds2! A few clarifications, just to make the design specification proposal more precise:

• Which specific buttons from the editor toolbar are you proposing to remove?
• Which specific project toolbar buttons are you prosing to remove? (Your screenshot suggests all of them, but you only mentioned the palette in the text, so I can't tell which you're proposing)
• When specifically would all of the hidden functionality be revealed? Some of them become important in throughout the tutorial. After they are revealed, would they always stay available?
• Can you clarify what you mean by "show an example of what the stage should look like"? Are you proposing to just show the output that the stage should show, or a whole duplicate stage that's not interactive? And when would this be shown? Most steps don't ask for interactivity, so are you proposing to have some way for each tutorial step to indicate a desired output?

Thanks for the clarifications!

[nhinds2]

Hi Amy! Here are some clarifications:

• Which specific buttons from the editor toolbar are you proposing to remove?

I am proposing to only have the “undo/redo” button and “select neighbor before/after” buttons on the editor toolbar because it is the most intuitive for the user to use and labels are the most explanatory for the user. I am also planning to keep the minimize, full screen, and language and mouse and keyboard toggle, as they are also commonly used by users and do not need prior coding context to understand.

I am proposing to remove the rest of the buttons. This is because the editor toolbar is not introduced, therefore a user doesn’t have ample tutorial for using it. This eliminates the problem of a user becoming frustrated with knowing what the buttons in the editor toolbar do when they are just starting to use the tutorial. Once they are familiar with the code after they have completed the tutorial, they will have the proper context to use all of the buttons in the editor toolbar in the actual code workspace, which reduces the confusion. I changed this design aspect so here is the updated screenshot for clarification:

Here is a close up of the proposed change to the editor toolbar:

• Which specific project toolbar buttons are you proposing to remove? (Your screenshot suggests all of them, but you only mentioned the palette in the text, so I can't tell which you're proposing)

I am suggesting to remove the "palette" and the “add file”/ "file name" buttons because the tutorial does not require multiple files. Thus, the project toolbar only needs the guide and the undo button. Here is the screenshot for updated clarity (In the previous proposal, I did not include the guide icon, but it is needed):

• When specifically would all of the hidden functionality be revealed? Some of them become important in throughout the tutorial. After they are revealed, would they always stay available?

After the hidden functionalities are revealed, they will always stay available. This is because once the user has been familiarized with the functionality, they understand how it works and can recognize it in the coding workspace. Due to this, the hidden functionality would only be introduced once the tutorial introduces the functionality.

• Can you clarify what you mean by "show an example of what the stage should look like"? Are you proposing to just show the output that the stage should show, or a whole duplicate stage that's not interactive? And when would this be shown? Most steps don't ask for interactivity, so are you proposing to have some way for each tutorial step to indicate a desired output?

I propose to show a whole duplicate of the stage that is not interactive. This would be shown only when the tutorial prompts the user to do a code task, so they have a non-interactive screenshot of what the tutorial expects. The buttons would not be interactive since they solely show an example screenshot of the desired stage. My reasoning for this is showing the full non-interactive screenshot of the stage would give the user a “match” for their expected output on their own stage.

[amyjko]

Thanks! Those seem like reasonable decisions. Integrate these into your design proposal in the main issue body text?

Re: duplicate of the stage, one more clarification: is the goal you're aiming for to have learners know when they've "succeeded" at following the instructions? I ask because not all prompts in the tutorial have a right answer — many are prompts to play and experiment, not to type in something in particular. Because of that, there is no thing to show that would tell them what to complete, because there is no right answer.

[nhinds2]

Hi Amy, I have updated the design spec body with comments.

To clarify your question: I want to let learners know that their stage output should resemble the tutorial, not produce the exact results. My thinking is that users will be able to play and experiment, but still have a general idea of the expectation the tutorial is asking them to do by giving a relative example of the tutorial. This can be seen in the screenshot the tutorial shows the name being typed (e.g. “Natalie”), but the learner types their own name (e.g. “Paul”). The screenshot of the stage would give an example of a correct-looking output of what the tutorial expects, but not a strict adherence to the example.

[amyjko]

Thanks for the clarification @nhinds2! I understand the rationale. One more clarification: are you proposing that it look exactly like the stage? I ask because that's very difficult to achieve, technically, because the stage view isn't designed to be shrunk down, nor would it be very legible if shrunk down to such a tiny size. On mobile it would be particularly tiny. Or more responsive design might be to just show the expected output, but not the whole stage view.

[nhinds2]

Hi Amy, I see what you mean, especially for the mobile version. I think it would be sufficient to only show a screenshot of an example output on the stage. It would also reduce confusion of users clicking on the stage screenshot and expecting interaction. Due to this, I agree with your proposal of a screenshot of the expected output but not the whole stage view (shown below):

[amyjko]

I think that's feasible. It can't be a screenshot — images are a last resort, given their accessibility problems — but it can be a rendering of example output, just like appears on stage.

[nhinds2]

The rendering of example output just like it appears on stage makes sense, thank you. I have updated the main portion of the design proposal with that information.

[amyjko]

Thanks @nhinds2! I think everything here looks good. I'm going to remove the needs design label here, approving your design, and label this buildable. Congratulations!