Indeed. However, the x on the top implies that’s where you tap to close (It fooled me for one, but maybe I’m just too old).
Done with tweaks for tonight, I think. I need to work on the exercises as some of them are IMO way too hard, too early. We want at least one or two softballs in the beginning of each before launching into tough stuff.
I’m also not sure a free playtime exercise at the end of every lesson is a great idea – people looking for an interactive tutorial want structure almost by definition.
I tested in Firefox and Chrome, and mobile safari and Chrome in the mobile emulator so far (should cover Android, mostly).
As long as @eh3rrera agrees, it’d be better if his original repo was simply moved over (after merging back any new changes from the fork) to the CommonMark org. Either that, or you should make a clean break.
A canonical repo doesn’t function well as a fork, since they have degraded functionality on GitHub such as no search.
Last exercise of “Emphasis”:
Can you change the last line to use a plain
*?
I did not understand this challenge. So far I’d been putting emphasis on things, so I thought this also had something to do with emphasis (having forgotten about the extra note about slashes in the intro), so I just haphazardly made some things italicised in hopes of getting it right until I checked for the answer and went “oooh”.
I’d rewrite the exercise description with a little preface about the problem at hand:
According to standard Markdown the bottom asterisk is the start of a list, but we would like to use it as a plain
*so that it looks like a footnote.
Intro for Links (and images)
There should be a clear separation between the two types of links, e.g. separating them with a header for “Link Type 1” and “Link Type 2”. The way it is currently presented, it looks like they might all be interconnected somehow, also because they use the same a.com example link.
Same confusion carries on with Images.
Second Images exercise
There’s no “Show answer” here.
1 Like
Good ideas!
I changed the description for the escaping example (this comes up a lot with people getting unwanted bold or italic, as * isn’t that uncommon in internet text) to:
Can you change the last line so the
*is visible?
I changed the link examples to use a.com and b.org so it is clearer they are different links, and for images cat.png and dog.jpg.
I fixed the missing Show Answer, there’s a fair bit of cutting and pasting going on here.
1 Like
All lessons and exercises are now complete for
http://commonmark.org/help/tutorial/
@jgm now would be a good time for you to take a look if you have time – it’s ready for serious feedback.
General
Why are the left ← and right → navigation buttons positioned atop of each other when the arrows suggest a horizontal navigational model?
To which beginning (set/lesson, tutorial) does “← Go to the beginning” go?
Why do “← Previous exercise”, “Next exercise →” and “Next lesson →” include no ‘go to’?
Does it really make sense to use plain arrows for exercises and lessons alike or should the latter use ⇤/⇥ instead?
Should the arrows really be literal or should they rather be incorporated into the shape of the buttons?
When I first checked the box for “Show generated HTML?”, which is not really a question, I assumed the content of the output box above would change since it’s a different view of the same content, but instead another box popped up below and pushed the nav buttons down, although there still was enough place left left of the new box.
It may be helpful to offer a reset option if any of the text that is not vital to the task has been changed by the user.
The success dialog “Great work! You did it! Keep going!” should not be modal, or if it is then it should have two buttons: default “next exercise” and “play some more with this one”. If I try to do play more with it the dialog pops up all the time when I’m navigating the text without having changed anything yet – annoying.
The dialog should also vary its congratulations, because the constant repetition of exaggerated compliments devalues them.
The OK button looks dim and therefore inactive.
I don’t understand why a plus symbol is used for the popup info in introduction code examples – nothing gets added. I also think that clicking/tapping them should work like right now, but mere hovering should also temporarily reveal the info (without the closing cross).
Please use proper, typographic, curly apostrophes and quotation marks. Thank you.
Exercises
-
Maybe the intro should be numbered 0. I was just confused when at the heading description there already was 03 showing, although I had completed just one set of tasks. But that’s a really minor point.
-
In the emphasis exercises I can use the underscore, too, although the task description only mentioned the asterisk. Maybe the success note should mention that.
-
In the heading description, the title says heading, but the text uses header.
Is it really appropriate to talk about “the smaller the header”? It’s the font size that usually decreases. The level is lower, the nesting is deeper. -
Emphasis and heading lessons introduce a single syntax, but the links lesson comes with both alternatives. I’m not sure which approach is better, but it should probably be consistent.
The concept and syntax of IDs/references isn’t explained at all (except by code), although it is perhaps the most complicated aspect for people not that tech-savvy, i.e. the target group.
The horizontal ellipsis character, though theoretically correct, doesn’t work well with the monospaced font and looks like a (mandatory) underscore or hyphen, try a vertical ellipsis instead⋮since it doesn’t look like something one is supposed to actually input.
Also, use “address” instead of “URL”.
I doubt random people will know what the link title is for or where they would encounter it.
Huh, the first exercise actually introduces the third alternative syntax – and it advertises some flash-only site.
The second task is to make an inline link, but if I solve it with a reference link it’s also successful without any critique. -
I just noticed that the validity check is not case insensitive, e.g. the alternate text must be “Logo” not “logo” in the second image exercise. Also, link and image titles had only be introduced for reference links, although (with this parser) they also work inline and are apparently expected to be used that way here.
-
“To create inline code” sounds misleading, confusing, wrong. Instead of ‘code block’ you might want to speak of ‘multiple lines of code’. The tutorial still hasn’t introduced paragraphs which are much more important to most people than code markup.
It’s good that most tasks don’t use computer code! But it’s confusing that the text still talks about “code” all the time.
If I solve the score table task with fences, a top fence suffices to trigger success – while technically true it’s not helpful that way, so add some content below the “table”.
If I include an optional info string in the JS/backticks task, it’s not considered successful. (Tildes and longer bottom fences work as expected.) -
The first quote task suggests bad use of a block quote, because it’s inside a paragraph, sentence even, which HTML doesn’t support.
-
Really? At this point, I thought this tutorial wouldn’t introduce paragraphs at all.
A paragraph or sentence cannot be a line break, just include one so please change “This is a\ line break.”, also you might want to stress that their use should remain an exception.
There’s a space missing before “265” in the first task. -
“Each list must consistently use the same list marker.” – The parser used (unlike many others) agrees, but since when is this specced? “Escape the marker” – that’s coder terminology unknown and alien to the average user.
-
Why are nested lists a topic of their own? They’re still lists.
The intro says 4 spaces were required when 2 are actually enough. It’s hard to enter a tab character here, so maybe don’t mention it.
The FIFA WC was in 2014, dunno ’bout Rugby.
The recipe task is the first (and only) that doesn’t inside the text box without scrolling. Avoid that, especially since the preview scroll isn’t synchronized. The indents confusingly need at least 3 spaces preceding them (not 2 as before or 4 as described). The example is arguably misusing an ordered list for numbered headings.
1 Like
Agree this part needs work… and I want to put in variable congratulation phrases here too.
Good point… perhaps this panel should superimpose the other panel? That might be better. We don’t even show this checkbox on mobile. edit: this change is complete, great idea, much cleaner this way.
Yeah these are a pain to type on Windows. Pull requests gladly accepted for little changes like this: https://github.com/coding-horror/coding-horror.github.io/tree/master/help
Great idea, I just changed it… vertical ellipse, I forgot about that!
Good point, will switch to http://html5zombo.com/
Yeah, we should probably switch to a lowercase conversion before the check. Edit: this is done, check is case insensitive and it already trimmed whitespace from the ends, for what that’s worth.
I agree paragraphs lesson should be earlier, maybe even first… I moved it to position #3 after the emphasis lesson.
Oops, let me correct that.
As for the last test requiring a little scrolling, it is the last and most complex test… so it should be a bit harder than the others.
As for 4 spaces, it seems the parser will optimistically decide when things should happen, but 4 spaces are indeed required in many circumstances even if the parser is able to decide earlier in some specific cases – I don’t think we should confuse people by including a ton of exceptions and caveats.
Remember the tutorial is for relative newbies to Markdown, not a master class for experts. My goal is to show common scenarios I see average users running into with Markdown – keep this audience in mind when you evaluate the tutorial.
It is in the spec, right at the beginning of section 5.3.
“A list is a sequence of one or more list items of the same type.”
where “same type” is defined to require the same bullet, or same delimiter in an ordered list.
You have some great comments here.
One general point: in a beginner’s tutorial like this, especially one that purports to be for Markdown (rather than CommonMark specifically), it is useful to teach techniques that will work, as far as possible, across implementations. I assume that was the reason for teaching the “four-space rule” for lists, even though CommonMark is a lot more flexible about list indentation.
However, if the \ at end of line for a line break is used, this is a CommonMark-only feature, and so inconsistent.
Personally, I’d prefer a tutorial that purported to be a CommonMark tutorial, and taught the CommonMark rules (to an extent suitable for beginners), e.g. for nested lists.
Nested lists; the more general topic would be, how do you include block-level content (including other lists) under list items? How much indentation is needed, etc.? I agree that having a separate pane for nested lists is a bit odd.
Disclaimer: I haven’t really had time to look through the tutorial in detail first hand.
Ok @Crissov all the major stuff you brought up has been addressed:
- show generated html is an overlay that replaces the HTML output
- success alert is no longer a modal dialog
- success alert varies text at random
- reset button appears if editor text changes from default
- validity check is case insensitive
I guess it would be nice to have a preview as well when you introduce a new concept in the tutorial. I mean a preview of what the markdown (with the red dots hanging around) looks like when rendered.
I have been through about 8 cycles of public feedback on the tutorial, with many iterative improvements, so I am comfortable it is in a good place to link prominently from http://commonmark.org now, and I will make that change later tonight.
Speak now or forever hold your peace, or … something 
Ok
has been updated (slightly) and has direct links to
on it…
http://commonmark.org/tutorial
is broken.
Hmm yeah, looks like it works on the live site though. So I’ll just delete that link from above.
oh duh, it’s supposed to be http://commonmark.org/help/tutorial/ my bad 
OK, I think I “got” them all, but y’all will have to “check” my work.
I would argue against using a.com and b.org, and a.png and b.jpg for links and image links.
It is not logical to say that the two expressions gives the same result with different urls, is it?
It would also be preferable that the result equaled the expression that made it, if space is permitted, so that the user can experience the true result of the expressions.
There should be a one-to-one connection that makes it instantly understandable to everyone.
This help page will be for beginners, some probably not even programmers.
And I don’t buy the argument (in a twitter exchange I had) that one should defer the details of this to the tutorial (links section is 3 clicks away, 13 clicks if you do the tutorial sequential).
You need a way to distinguish between the two links, or else newcomers might think that the entire 3-liner is all one link, with an awfully complicated syntax. I wouldn’t mind the links being identical if they were more clearly visually separated in another way, e.g. by putting a big and bold “OR” after the first link.
Feel free to do a mockup for it or send a PR if you have a good way to show readers “Here’s method 1, and here’s method 2” without getting too verbose.
I think the page is great as it is, and that the OR is quite visible to separate the alternatives.
I see your point, but I think that someone who would think that the the two alternatives belongs together would get it wrong even if it where a/a or a/b.
Not a big deal for me, someone asked for feedback on Twitter, I thought it made more sense my way, and then it became a bigger issue that it should have…
Thank you for a civil reply and for taking your time.
Tor
1 Like
What a nice and stylish tutorial!
One small suggestion (first “notch” in “05 Links”): The blurb about reference-style link definitions says:
The link definition can be placed anywhere in the document, but is generally at the bottom.
What if a novice tries, for the exercise that follows, to put the link definition “anywhere, and generally at the bottom” like this:
You can do anything at [this site][id]
[id]: http://html5zombo.com
It’s certainly easy to then find out what’s wrong by trial-and-error (or maybe this is even intended as another exercise?), but how about mentioning the required blank line? Maybe:
Link definitions can be placed after a blank line anywhere in the document, but they are generally written near the bottom of the document.
1 Like