Feedback on our interactive Markdown tutorial


#1

We’re are 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:


#2

Finished the tutorial. Overall, I like it, I think it is a really good introduction to Markdown. I just had some bits and pieces that I found:


Potential bug: After completing an exercise any cursor movement within the input area pops up the “Great Job” dialog.

Steps to Reproduce

  1. Launch the interactive tutorial
  2. Go to the first exercise
  3. Surround the words “American Oxygen” with two asterisks
  4. See the “Great Job” dialog come up
  5. Press Enter to dismiss
  6. Click to place your cursor anywhere in the middle of the input area
  7. Press Left

Expected: Caret to move left one character position
Actual: “Great Job” dialog is displayed again and the caret is moved left one character position


Suggestion: I expected the “Show generated HTML?” preference to follow me from each page to the next


Potential bug: Section 3 - Headings — In experimenting with the various heading levels, I noticed that the <h4> style is larger than the <h3> style. I expected it to be smaller. <h5> and <h6> were as expected.


Potential bug: The color of the Ok button on the “Great Job” dialog appears to be less saturated than the other buttons on the exercise pages


Suggestion: Section 7 - Blockquotes — When asked to place the quote of Carl Sagan’s in a block quote, the correct answer according to the tutorial is to leave the double-quotes around the passage. Typically, one would remove the double-quotes when block quoting something.


Suggestion: Section 9 - Lists — You may want to mention why there is a rendering difference between using all of the same character (e.g. all asterisks) in unordered lists versus using a different character for each item in the list (e.g. asterisk, minus, and plus)


#3

Yeah the accomplishment dialog could use some tweaking. I also want to vary the success text a bit.

The “skeleton” CSS that was used has bizarrely massive heading settings. The tutorials don’t call for any H3 to be used, though.

Yes, the instructions could specify to remove those, I suppose.

There is no rendering difference… see http://spec.commonmark.org/dingus/?text=-%20item *%20item %2B%20item

Show generated html is kind of an advanced thing, and isn’t even shown on mobile.


#4

The different bullet character list renders with more space between the bullets than with the same bullet character:

http://spec.commonmark.org/dingus/?text=%20item%0A%20item%0A*%20item%0A%0ATest%0A%0A*%20item%0A-%20item%0A%2B%20item%0A%0A


#5

Ah, you’re right, looks like in CommonMark varying the unordered character creates a new list… did I actually use random unordered characters anywhere in the tutorial though?

Why are you bringing this up – I’m unclear?


#6

I don’t know if it is important, but you might mention that you can specify the language in a code block.


#7

No, you didn’t mention mixing the characters in the tutorial. But you did specifically mention that one can use any of the three different symbols and, in my experience, someone will attempt to infer that it doesn’t matter which symbol you choose. In most cases it doesn’t, except when it does :laughing:

The tutorial is interactive and offers a great live view of the rendered version of what someone types, just as the CommonMark widget does. Some people will wander off script to experiment with different things to see what happens. Personally, I do this in every interactive tutorial I use and see it as one of the major benefits of this type of teaching. I don’t know what exactly your plans are for the tutorial, so I was thinking about how people might become confused when things didn’t act as they expected … even when going slightly off script.

If people going off script isn’t a concern, then don’t sweat it :grinning:


#8

Sure, I added h1,h2,h3,h4,h5,h6 support for the preview.

I added the text

Each list must consistently use the same list marker.


#9

I deployed a bunch of improvements based on feedback here, including the success non-modal repetition, a reset button for each excercise, and I added a little :tada: flourish at the end.

So have another look!


#10

There needs to be a better way of accessing specific sections of the tutorial. For example, how can I practice the headings section without going through all the sections that come before it?

Perhaps there could be links on the reference page that jump you right to the related exercises?

[EDIT]
It would also be good if you could stop the animations when the popup is open, they are a bit distracting.


#11

Use the right hand nav (the squares) or, if you are on touch, the bottom nav.

These should be quite visible on desktop now as I make the lesson titles visible from the first page of each lesson, only hiding the titles when you enter an exercise and we need the room.


#12

Much better! The only other piece of feedback I have is that when the success non-modal is up, the text input is still focused. It was a little surprising that typing anything other than Esc would go into the text input but not dismiss the dialog. Not a big deal in any way, but figured I would mention it.


#13

Disclaimer: my feedback is mostly based of consistency and user expectation, as this is what I’m used to being stuff that surprise-confuses users when I’m doing technical writing (I’ve done a couple of years of it).


There doesn’t seem to be any check if you’re completing the exercises correctly. This let’s me go to the next exercise without any kind of information that I did it wrong:

Being an exercise, I was expecting some kind of indication that I was doing it correctly (or not).

EDIT: on the paragraph chapter I got a success indicator, but not on the emphasis ones? Now I’m confused.


The links chapter shows how to do links with []

but the very first exercise is talking about <>, which doesn’t follow at all.

The way it’s done on the images chapter is what I first tried on the links chapter. I actually did not even know you could do <link> instead of [](link).


Exercise asks for inline title

But there is no indication of this syntax in the chapter instructions, only in the reference style.


This doesn’t seem right. I don’t see how it makes sense. Should it look like A literal backtick (`)?


Exercise calls for 4 space indentation on sublists

SHOW THE ANSWER use 2 spaces, and success prompt is shown at the second space input of the last line even when everything else is formatted using 4 spaces.


Answer uses 4 spaces for sublist, but 3 spaces for paragraph/blockquote. Didn’t know that could work.


As an aside, I really really really wish http://commonmark.org/help/ was the landing page for http://commonmark.org, and top result on google for markdown. Every week or so I google markdown for such a table but the top results aren’t nearly as concise and comprehensive.


#15

There is, if you don’t hit it, you didn’t match the success HTML output – it checks output, not input, so there can be multiple ways to achieve the same HTML, and thinking outside the box, etc.

That is kind of the point of the exercise… unfortunately (or fortunately?) most Markdown implementations do auto-linking, meaning they turn any URLs they see in text to links automatically. But this is not universally true, and brackets force it to happen, hence the lesson.

Hmm, good point, I hate to make the first example super complex, or maybe I could make this a reference style image link… I think I will do the latter.

Yes it should, the trick is “how do I display a backtick”, I think I should be more explicit that code blocks display all characters verbatim in the help text. For example

`` ` ``

This is kind of a super advanced scenario though… maybe I should just drop that, it’s very detailed for no reason, super advanced Markdown ninja stuff.

As for spaces, the official value is 4 spaces, but the parser may be able to (in some situations) optimistically determine which indent level you want based on fewer spaces.

I updated http://commonmark.org to have a direct and obvious reference to the help page, which in turn links to the tutorial.


#16

Perhaps on the intro image for the tutorial there should be an indication of the <> syntax then, since the first exercise makes use of it as the shown answer?

Forgive the bad mockup.


#17

Not really, since it is almost universally optional in practice, more of a “nice to know” than “essential to know”.

For example try entering an URL in the editor here and see what happens.


#18

You’re totally right, my bad!


#19

It is a tricky thing, because technically the < and > to make URLs is absolutely essential… but in practice almost every place I know of that uses Markdown also auto-links URLs.

So… it is a legitimate thing to be concerned about. I felt people should know about it, just in case, because for some unusual URLs you may be forced to put angle brackets around them as the auto-linkifier can’t quite make it work.


#20

[quote=“codinghorror, post:19, topic:24072”]
technically the < and > to make URLs is absolutely essential… [/quote]

Maybe this could find a spot on the cheat sheet ? Auto linker sometime cuts the url in the middle and fixing strange url is probably more general public than the [1] bibliography style to make a link.

Also I tend to think that hand-on part should probably cover the most common scenario. If angle bracket are only good to know, maybe they belong in a note somewhere.


#21

It is quite rare to find an URL so oddly formed that the autolinker can’t link it. Regardless this is indeed covered in the 10 minute tutorial at http://commonmark.org/help