Feedback on our interactive Markdown tutorial


(Jeff Atwood) #1

We’re putting together the user-friendliest Markdown tutorial we possibly can at:

http://commonmark.org/help/

If you have a chance, can you take a peek, try the interactive tutorial, and let us know what you think?

All feedback welcome. :mega:


How to translate the Markdown tutorial
(cpradio) #2

So the only suggestion I have, is to make it easier to get back to the original text. On the last Nested List exercise, I accidentally removed some of the text, and had a heck of a time getting that text back. I eventually had to refresh the page and go through the first 2 or 3 nested list excersizes again to get to the final exercise.

Having a “Start Over” button for each exercise that puts the input back to its original state would have been nice.


(Jeff Atwood) #3

Sure, have heard that from @erlend_sh before :wink: — in the meantime select the lesson from the navigation (on the right, on desktop, or at the bottom, on mobile) to reset the lesson.


(cpradio) #4

Yeah, that does the same as a refresh, so I would still have to complete the first two sub-exercises for nested lists to get to the final one :slightly_smiling: Was trying to not have to redo them again to get to where I was.


(Joshua Rosenfeld) #5

The section on block quotes, 1st question is unclear in its description.

It says:

Can you make the section in quotes a blockquote?

To me, I wanted to type the following:

The quote 
> Somewhere, something incredible is waiting to be known

has been ascribed to Carl Sagan.

No quotes when making the blockquote. However, it is looking for:

The quote 
> "Somewhere, something incredible is waiting to be known"

has been ascribed to Carl Sagan.

Maybe it is just me, but I would remove the " when turning something into a blockquote.


(Jeff Atwood) #6

You can navigate to individual exercises (at least on desktop) using the circles at the bottom of the page. There’s one circle per “page” of the lesson.


(Jeff Atwood) #7

Yes this is coming up elsewhere so I will likely make the instructions more explicit here.


(cpradio) #13

Hmmm I don;t remember seeing little circles anywhere. I’ll have to give it another shot tomorrow.

Edit: Yep, I see them now. Never noticed them before, probably because everything else had my gazed up at the top half of the screen that I never bothered to look at the bottom half.


(Dave McClure) #14

exercise 4 on the emphasis lesson is a little weird to me since it’s in the section about emphasis.


Can you change the last line so the * is visible?

I am totally awesome.*
* for certain very small values of awesome

I feel like it should instead be something like:


Can you change the line below so that “awesome” shows up with asterisks around it instead of in italics?

I am a totally *awesome* person.


(Jeff Atwood) #15

Your example is one I have never seen in the wild, ever. The whole point of asterisk emphasis is to turn what you typed above into italics. Whereas regular people do use asterisks for other regular people stuff and get in trouble doing so with markdown. Hence teaching escapes early.


(Dave McClure) #16

Fair enough… But it still feels a little incongruous since I haven’t been taught yet at that point that asterisks and dashes are also used to create bullets in an unordered list.


(Dave McClure) #17

In this example, it’s not so obvious that escaping the dot to make it not a list actually does anything since the styling of the ordered list has no indentation.


“We don’t want a list here. Can you fix it?”

1986.  What a great season


(Dave McClure) #18

In the first “nested list” example, I was able to nest the list by only indenting each sub-item with two spaces, but the instructions on the page before indicate that four spaces are needed…


(Dave McClure) #19

On the third “nested list” example, the text is pretty long. The preview doesn’t scroll with me and grabbing the bottom corner of the text input area to make that longer doesn’t make the preview longer either. So I can’t see what’s happening as I get toward the bottom without scrolling manually

… that’s all I got!


(Jeff Atwood) #20

The point of the exercise is to make a * a *, and that’s an emphasis character which does get used pretty regularly by normals… and to teach people very early on …

if stuff gets jacked up, start escaping special characters!

I dunno, you might be overthinking this a tad. I am loathe to move all talk of escaping way deep into list lesson, when normals run into escaping problems kinda frequently in Markdown.

Good point, there were a few problems there:

  • the sentence wasn’t long enough to show text wrap
  • the annoying skeleton.css originally used to build this tutorial overrode the list styles so no list indent was being used for numbered lists
  • the left padding required for a 4 digit number is much bigger than we need elsewhere so I made the css specific to this exercise.

I guess we could use the other common problem I see, other than “ascii asterisk footnote” which is the faux signature block… that’s also a list.

Blah blah blah blah

- Jeff

Yes, thanks, I will correct that.

What device are you on? There are @media queries for height that set the height of the editors based on how much vertical space there is. Also I can drag the textbox just fine in Chrome?


(Dave McClure) #21

However, the last example (pictured below), does require four spaces for the nested bullet list under the 1. to get nested. So not sure if that 2-space observation is a tutorial issue, a commonmark spec issue, or an issue with the implementation used by the tutorial…

Mac OS X laptop in Chrome:


(Jeff Atwood) #22

Let’s just keep the numbers at the official values. It looks like depending on where the parser is, it can guess sooner, but 4 spaces is the correct amount, so I am changing that back.

Looks like these are not working for you:

@media (min-height: 600px) { /* iPhone 6
@media (min-height: 700px) { /* iPhone 6+
@media (min-height: 900px) { /* desktop

so I added a

@media (min-height: 800px) {

Not much more I can do other than that.


(Dave McClure) #23

Oh, it was the combination of the bookmarks bar at the top and the downloads list at the bottom which brought the height down below 900px.

Everything but the last line is displayed now when I first load that page if I hit the 900px break-point:


(Nick Sahler) #24

Here’s some feedback I have based on my run through. I haven’t read through all of the feedback above, so I may be repeating some - but I’ll try to keep it terse as these are mostly nitpicky:

  • I think you should be able to completely navigate with the enter key once you complete an exercise. It felt awkward being able to hit enter to close the “good job” dialogue, but not to go to the next problem (and instead having to reach for my mouse or tab to the next button) [kinda fixed]

  • Fix or disable broken textbox resizing


    max-width: 100%; seems to do the trick if you want to leave it scalable vertically. [fixed]

  • Force using ``` to close code block as well as open. Unsure if this is intentional, but it accepted my md as completed even though I had not properly closed my code block (since it’s tokenized anyway, I assume) (noticed in 06-code.html)

  • Less importantly: the shadow on the tooltips feels a bit too intense.

Update:

  • Showing a faded version of the map gave me a better sense of orientation as I navigated through the tutorial. I didn’t feel kinda floating-in-space-y

(Jeff Atwood) #25

I kind of agree with this, but we need to make sure the width is there for it… and on mobile we don’t show that at all.