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.

[Gazook89]

I know it's early in development, but I think you should shoot for complete sentences (meaning just add periods at end of sentences). Also, on this line you have a typo (respectively). I suggest a slight rephrasing:

There are 3 editors: Brew, Style, and Properties.

Use each editor tab to edit your brew text (Markdown/HTML), styles (CSS), and properties.

[Gazook89]

You could just use <p> tags instead of spans, and then style them how you want.

[5e-Cleric]

p elements are block level elements to describe paragraphs. spans are used to apply CSS style and/or class(es) to an arbitrary section of text and inline elements. I believe my choice to be more appropiate for this specific use.

[Gazook89]

Placing the buttons within the actual explainer divs would be more intuitive to me-- the explainers should already be drawing the eye to themselves so it makes sense to place the related buttons right there with them. In particular, if something is annoying me on a screen like a popup, I want the dismiss button to be within the immediate vicinity of that annoyance, not some other faraway place on the screen.

[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.