Feedback for triage: Walking through tutorial end-to-end

[saraford]

I walked through the tutorial (took about 45 minutes end-to-end to capture my notes) in response to @coding-horror tweet. Funny, I feel a bit guilty now using the GitHub keyboard shortcut to generate that link :)

I figured I'd put all my feedback in one issue so you can split into multiple issues if valid. Hope this works. If not, I'd love to hear your feedback!

Homepage

1. Begin Lesson button changes from blue to red after a few seconds.

Made me do a double-take, like "did something move on the page?"

2. Suggestions to wording on homepage - Avoid passive voice

Feel free to ignore me. My high school English teacher taught for 50 years, including through two(!) Category 5 hurricanes (may she rest in peace). I feel an obligation to pass along her teachings. :)

 "Each lesson introduces a single Markdown concept with a simple example." 
 "Complete a few practice exercises with your new knowledge." 

And I'd move the "Experiment and have fun!" to last line. Otherwise, I stop reading after "have fun!" :)

3. "Select the red pulsing circles for details." I was looking for these on this page. Perhaps...

 "Select the red pulsing circles in the tutorial for more details."

4. The right nav bar is blurry when hovering over

While you're moving your mouse over the nav bar, the text get blurry. But as soon as you stop moving, the text clears up.

Interactive tutorials / Instructions

1. During the exercises, the "You got it right!" appears before I can visually confirm my answer in the right panel.

I feel like I'm guessing whether my answer is correct. I could use the visual confirmation to help write the muscle memory. I think CodeAcademy has a good implementation of this where the user asks to verify answer when he/she is ready to check their work.

If the CodeAcademy example doesn't work, could this box be smaller or placed somewhere else, maybe above the two boxes? Or near the "Show the answer" / "Reset" buttons?

A good example is on the hurricane page. I thought there was no space in-between the [1]: and the https in the reference link, but before I could confirm, i got the "you got it right!"

2. I think 03-paragraphs is broken

At the beginning, make note of the right box (answer).

but after you hit "Show the answer", the right box (answer) changes!

3.Are URLs required to be in < >?

In 05-links, the text says

URLs may not become links in Markdown until enclosed in < and >.

Is this "may" as in optional or don't become links? This is the question I had when I read it.

4. Put Show Generated HTML in a tab?

I'm wondering if the Show Generated HTML / results should each be in a tab, instead of a checkbox at the bottom, to increase usability.

⚠️ Warning: PM UI Mockups ahead ⚠️

5. Not a bug

Was this a hint? :)

*6. Use +, , and - as list markers**

I have trouble understanding what this means. Are these used in conjunction with each other, e.g. does *+ have meaning?

7. 10-nestedLists gives correct answers when things aren't :100: correct

It said this was correct.

8. 10-nestedLists doesn't always work

There's something odd with this one. I had to click inside the editor to get it to confirm my answer was correct.

Ending

I was half-expecting "Go forth and Markdown beautiful text!" :)

[coding-horror]

This is awesome, thanks for the super detailed feedback!!

Homepage

1. Yep, intentional, we want people to realize "THIS IS THE NEXT PAGE BUTTON" ;) Was implemented based on earlier rounds of feedback when people were confused about what to click next.
2. Good ideas, improved that copy!
3. Ditto, added a bit of extra copy to make that clear.
4. Browser software / OS issue, above my pay grade..

Tutorials

1. I don't think adding another button is a good idea, frankly. More buttons == more confusion. I can support adding a pause here so it's less immediate, though! I have heard that complaint before, that the completion is awfully .. abrupt. Let's try 1 second so it's a bit less robotic and jarring.
2. What's broken about it? It says "so the lines end exactly as shown in the editor". Think HTML..
3. They are technically required, but most implementations auto-link URLs anyway, which is "off book", but a very common practice. It is a good rule to understand since putting a URL inside <> forces it to be linked, and is correct by strict Markdown rules.
4. I think that would give Show Generated HTML unwarranted priority in the UI; this is a power user function for advanced people, not something I think would benefit the average user stumbling across it, who just wants to type some formatting. So having it be in grey, at the bottom, with a checkbox is more correct.
5. :) Miss Manners is the BEST
6. Choose one of these. Let me add a word.. you can have lists with different marker types. Try experimenting.
7. Correct, Markdown is very "forgiving" which is part of the reason we got in this pickle in the first place.. there's sometimes many ways to achieve a given formatting, and sometimes they conflict. As long as the HTML output matches, you have achieved the goal, regardless of the specifics of the markdown, e.g. you can use ** or __ to make bold and both are fine and will move the lesson forward, because they both produce <b>
8. I am guessing something similar to #7?

This was great stuff!! Thanks, implemented in

https://github.com/commonmark/web/commit/780b890ca8a0eca44359a3fc77d2da827996c955

[saraford]

This is awesome, thanks for the super detailed feedback!!

No worries! Glad it was helpful.

Homepage

Yep, intentional, we want people to realize "THIS IS THE NEXT PAGE BUTTON" ;) Was implemented based on earlier rounds of feedback when people were confused about what to click next.

Gotcha, but why not keep the button red the entire time? When it is red, the button is the most salient item on the page. I'm very curious if you tried keeping it a solid red before and it didn't work.

Tutorials

I have heard that complaint before, that the completion is awfully .. abrupt. Let's try 1 second so it's a bit less robotic and jarring.

👍 Less is more wrt UI. Adding a delay was also in the back of my mind, but finding the right time delay will be key. Too long and the action will be unexpected.

What's broken about it? It says "so the lines end exactly as shown in the editor". Think HTML..

Oh wow, that took me about 10 tries to figure out! I was thinking the editor was the right-hand box, not the left hand box. I blame too many years testing VS :)

I think that would give Show Generated HTML unwarranted priority in the UI

👍 Agreed. There's more benefit to the simplicity.

I am guessing something similar to #7?

The "you got it right!" box didn't appear until I randomly clicked inside the editor, but I only saw this once of probably a 100 times throughout the tutorial. I don't have a repo, so probably just human error :)

This was great stuff!!

Happy to help!