Feedback on our interactive Markdown tutorial

meta
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:

1 Like
2

This is kinda funny, I was complimenting my team on how great our documentation is just four hours ago, and you pull the same thing :smiley:

$good_docs++;

(I’ll go through it in depth in a bit)

Edit

Ooh, emojis have changed?

Edit

I am a curmudgeon. I don’t like labels for links when browsing on my phone at all. I am in the minority, but I want to see the URL for user generated content.

1 Like
3

Ok I folded in some early feedback and minor fixes from a few other places I posted this. So take a peek when you can, and give the exercises a shot.

bragging.png650×618 32 KB

2 Likes
4

This is great for dummies like me! Thanks!

1 Like
5

I haven’t tried the actual interactive tutorial yet, but:
Let’s say someone asked, “How do you make the text bold?”

How would you type: **text** without typing text? Or is that the workaround: to throw it into an inline code block?

Edit: Oh, and this may just be because I’m not particularly observant, but I tried multiple times to get the (not-inline) code block thing to work before I realized that the instructions on how to make a code block were in the example code block.

Edit 2: …aaaaaand my answer is on the very first page of the interactive tutorial. Never mind, I’m an idiot.

5 Likes
6

What would Jamie Zawinski Say (JZWS)?

7

Thanks, was it clear what to do? Anything we can improve? Any bits that were confusing or could be better?

I… don’t know? What do you say? Any feedback?

Anything else to say @japhroaig did you finish the tutorial? There’s a little fun thing at the end…

8

I will totally steal this phrase, hope you don’t mind.

1 Like
9

Oh crap, no. I promise I will. I looove good docs, so i may have some nitpicks but it is already great.

10

I know Markdown pretty well but it looked good to me.

11

Crashes at http://commonmark.org/help/tutorial/09-paragraphs.html?

After blockquotes, it should go to http://commonmark.org/help/tutorial/09-lists.html?

12

Sorry, just fixed that, my bad. We moved paragraphs up since they are so fundamental (and simple).

13

But how do you write an octothorpe at the start of a line? I hate how any attempt to be funny using some #humor ends up being
#huge
instead. :frowning:

14

#likethis?

#backslashtobreakout

1 Like
15

:slightly_smiling:

 

16

Perhaps this is outside the scope, but colon smilies aren’t always being interpreted correctly.

Screenshot_20151231-215125~2.png1039×1110 198 KB

I’ll get onto the help after I get out of this pub and can concentrate.

17

Doesn’t matter too much since in CommonMark the space between the hash and the text is now required to make a <h1> header. You can view the relevant discussion here.

That said the tutorial covers escaping characters not just once, but twice!

We will switch to a 100% CommonMark (aka standardized, properly specified Markdown) compliant renderer here in the next 4 months without question.

18

#TIL

Thanks!

19

I wrote a second post, but I don’t know where it went, so I’ll rewrite it as best I can.
Three notes:

  • I like that the tutorial judges based on output, not on input - that is, it doesn’t matter how you get the effect you’re asking for, as long as you succeed in doing so.
  • In addition to the “solve this for me” button, I’d like a “hint” button to show an example of working code. I’d rather figure out what I’m doing wrong myself and fix it by trial-and-error, so that I can figure out what won’t work. For instance, I had trouble with both the reference-style links and the reference-style images, until I figured out that there needs to be an empty line between the bottom of the paragraph and the reference, and that the reference doesn’t need to be in parentheses. Had I just clicked “solve,” I might have missed what I was doing wrong.
  • Finally, I’m really bad at reading instructions, which is totally not your fault, but I’m probably not the only one. When you’re asking us to do something only to one part of the sentences, can you emphasize what part that is? For instance: please put only the math into inline code blocks -on my first attempt, I misread and put the whole line into an inline code block.
    It’s a great tutorial, thanks!
20

The numbered list, while technically correct, is misleading. It implies that you have to do the sequencing yourself, because you used sequential numbers in your source test. Had you numbered each line with just “1.” it would be more clear that Markdown does the sequencing for you.

1 Like