Simple tutorial

[5e-Cleric]

Simple editor tutorial on newpage

This PR adds a simple 4 step tutorial for new users.

This is a prototype, i want feedback, colors, fonts, accessibility, everything.

To restart the tutorial, erase the dissmiss_tutorial localstorage item. Similar to notificaionPopup, this only happens the first time you come in the site.

[Gazook89]

Without commenting on the rest of it, the first thing that I notice is that I would change “brew lane” to “preview pane”. “Brew pane” is too ambiguous about what is being done in the pane— arguably the left pane is also a “brew pane”, since it contains brew text. Even more importantly, the tooltip for the markdown editor tab shows “Brew” when you hover over it— which makes me think THAT is the Brew Pane.

“Preview Pane” describes what is being done in the pane— you are previewing your brew.

I feel like this week I am trying to strong arm my naming conventions on the project, so pardon me if I’m being obnoxious.

[Gazook89]

I also think that this is the kind of thing an Issue should be open for first, to discuss what problem this actually solves and different possible solutions. Then, a PR can implement a desired solution and the comments can be focused on the code itself.

[dbolack-ab]

Without commenting on the rest of it, the first thing that I notice is that I would change “brew lane” to “preview pane”. “Brew pane” is too ambiguous about what is being done in the pane— arguably the left pane is also a “brew pane”, since it contains brew text. Even more importantly, the tooltip for the markdown editor tab shows “Brew” when you hover over it— which makes me think THAT is the Brew Pane.

“Preview Pane” describes what is being done in the pane— you are previewing your brew.

I feel like this week I am trying to strong arm my naming conventions on the project, so pardon me if I’m being obnoxious.

FWIW, I agree here. You might go with a "Brew preview pane ( preview pane hereafter)" type phrasing to help glue the two panes together further but without the ambiguity. I might consider "Brew Editor pane" similarly.

[Gazook89]

But why use “brew” at all, if both panes are “brew something”? It should be self evident that you are talking about a brew or else “brew” should be defined earlier, as the Homebrewery’s name for “document”.

[5e-Cleric]

I feel like this week I am trying to strong arm my naming conventions on the project, so pardon me if I’m being obnoxious.

On the contrary, i 100% agree on establishing names for everything, helps us, helps users.

will change name to preview, and brew to text in editor as well.

As soon as we get a deployment, i recommend testing it, it is very quick.

[calculuschild]

Deployment created

[Gazook89]

Looking at the deployment now:

A. It might be too much to have the tutorial start automatically when you click "Create Your Own". Consider adding another button the homepage, so the options are "Start with Tutorial" and "Create Your Own".

B. The "Skip" button could be renamed to "End Tutorial". Right now, "skip" makes me think I am skipping just one step...it's not clear enough about what is being skipped, and since at this point you are already in the tutorial, it's more clear to say "end it" rather than "skip it".

C. I would include a step counter somewhere, so the user knows upfront that this is only x number of steps.

D. As stated earlier, the "skip" and "next" buttons (whatever name they are given), should be inside the "explainer" popup. If the popup is meant to draw my eye to it, I don't want to then have to look elsewhere for the buttons even if they are big and obvious on the page.

E. If D is implemented, that likely means that there is only one explainer popup for each step, rather than showing multiple popups at once. This goes back to my point about where your eye is being drawn to-- don't divide the attention. And having a single popup at any time means the 'next' and 'skip' buttons have an obvious place to be.

F. If there is a single popup for each step, you can add a little bit more info in each step (since they won't seem as heavy with info). If this is a tutorial, I think it's not necessarily bad to say a little more as long as it's respectful of the users time as well as informative.

G. There should be some way to clear the Dismiss-Tutorial key in localStorage or otherwise find the tutorial again. Maybe if implementing suggestion A above, the "Start with Tutorial" button is always visible, regardless if the tutorial has been done before. Or, add it as an option in the help menu.

H. You might consider finding a way to actually style the relevant elements directly, rather than drawing a new box around them based on their dimensions. Use border or outline (outline is probably harder in this case). This way you know that the element is highlighted correctly--- right now, it's very easy to ruin the highlighting, for example by resizing the window:

I. Is the <dialog> tag a better option for the explainer box, instead of <div>?

J. I would set the font to Open Sans, to match the rest of the UI.

K. Maybe change "Finish" to "Let's get started!" or similar. I dunno...obviously less important.

Anyway, that's a lot, sorry to bombard. I think a tutorial will be very helpful for people with no experience with these types of editors.

[5e-Cleric]

That is a lot of points, the one i don't get is H. i have code in place to set the size of the splitpane so that doesn't happen, it worked fine when i opened this.

Will answer the rest after i go to sleep.

[Gazook89]

Regarding H: it seems like this is just setting the size of the pane boxes to 1/2 the window width, which works on New because that is the default until someone has used HB and manually changed it. You have a resize event, but it just does checkTutorial— it should be recalculating the width of each pane and applying to the pane overlays (or some equal method).

With this, you could even include in the tutorial “move the divider to resize your panes” and it would work.

[5e-Cleric]

A. It might be too much to have the tutorial start automatically when you click "Create Your Own". Consider adding another button the homepage, so the options are "Start with Tutorial" and "Create Your Own".

It does not start specifically when you click the button, just anytime in the newPage, but adding a button directly seems like a good idea too. Will add this.

B. The "Skip" button could be renamed to "End Tutorial". Right now, "skip" makes me think I am skipping just one step...it's not clear enough about what is being skipped, and since at this point you are already in the tutorial, it's more clear to say "end it" rather than "skip it".

I have seen many tutorials with this schema that work just fine, but don't mind the change, is skip tutorial good enough?

C. I would include a step counter somewhere, so the user knows upfront that this is only x number of steps.

Great idea, will add this.

D. As stated earlier, the "skip" and "next" buttons (whatever name they are given), should be inside the "explainer" popup. If the popup is meant to draw my eye to it, I don't want to then have to look elsewhere for the buttons even if they are big and obvious on the page.

Yes yes, i'll just have to rebuild the html and css from the ground up, no problem.

F. If there is a single popup for each step, you can add a little bit more info in each step (since they won't seem as heavy with info). If this is a tutorial, I think it's not necessarily bad to say a little more as long as it's respectful of the users time as well as informative.

I'd like more info on this, what do YOU think i should add as text? i tried to be concise, and am not sure what else to include. Might include more steps.

G. There should be some way to clear the Dismiss-Tutorial key in localStorage or otherwise find the tutorial again. Maybe if implementing suggestion A above, the "Start with Tutorial" button is always visible, regardless if the tutorial has been done before. Or, add it as an option in the help menu.

Reasonable. makes sense.

H. You might consider finding a way to actually style the relevant elements directly, rather than drawing a new box around them based on their dimensions. Use border or outline (outline is probably harder in this case). This way you know that the element is highlighted correctly--- right now, it's very easy to ruin the highlighting, for example by resizing the window:

It is a good idea, i'd still prefer no interaction from user to tool while the tutorial is active though.

I. Is the <dialog> tag a better option for the explainer box, instead of <div>?

Probably

J. I would set the font to Open Sans, to match the rest of the UI.

Huh, the font was open sans, must have missed the declaration somewhere i guess.

Anyway, that's a lot, sorry to bombard. I think a tutorial will be very helpful for people with no experience with these types of editors.

This is exactly the kind of review that i wanted, unfiltered, opinions on how to improve UX which is ultimately the goal of this PR, thanks.

[Gazook89]

Skip tutorial is fine.

I can come back with some suggestions on content later

[5e-Cleric]

Let me push this down to draft, until my more serious projects are merged, i don't want anyone focusing on this while more important PRs are abandoned.

[dbolack-ab]

But why use “brew” at all, if both panes are “brew something”? It should be self evident that you are talking about a brew or else “brew” should be defined earlier, as the Homebrewery’s name for “document”.

To enforce the logical tie between the two. Sometimes you need to be as subtle as the Anvil chorus.

[Gazook89]

To enforce the logical tie between the two. Sometimes you need to be as subtle as the Anvil chorus.

Maybe if there was multiple sets of things being tied together. In this case, there are two large portions of the page, which are further linked by the fact that one immediately changes the other. And their relationship is demonstrated on the first page that a new user sees when they first navigate to the site.

In the interest of brevity, which is my interest if I'm providing help to many users, I want to just say "Preview Pane" and be accurate to the 'official name' and consistent with others. If the "official name" is Brew Preview Pane, we will have some people saying "Brew Preview Pane" and some others saying "Preview Pane"....hardly a chernobyl but a senseless distinction.

Doubly so because prefacing "Preview Pane" with "Brew" adds virtually no value in terms of actual information. It's fluff.

my $0.02 at least. I don't think I can be persuaded so I wouldn't waste time trying, but this isn't hinging on my approval either.

[5e-Cleric]

I don't like almost anything of this PR right now, keeping it as a draft in case somebody wants to take it, but not sure i want to keep pushing it.