CommonMark tutorial / help page feedback

Jan 2016 — this is now permanently live at Markdown Reference

As previously announced, the winner of the CommonMark tutorial contest is @eh3rrera.

We’re grooming this to be a public tutorial hosted at commonmark.org perhaps at learn.commonmark.org or help.commonmark.org or something like that.

Esteban has generously contributed several rounds of feedback and bug fixes that @jgm and I have provided. Now it’s our turn to take over, fork the code, and make further improvements. So I have forked it at:

https://github.com/commonmark/markdowntutorial

What I’m looking for is community feedback on the live tutorial

http://eherrera.net/markdowntutorial/

I’ll be making whatever copy and code changes are needed. So please, take a look, and let us know what you think can be improved or changed in advance of moving this to the commonmark.org domain as an “official” help, tutorial and reference page!

i18n should be supported.

2 Likes

This looks like a good tutorial. I recommend the following changes:

  • Remove Github/Reddit tabs from the front page and any other references to non-CommonMark flavours of Markdown throughout the tutorial.
  • The mystery meat navigation on the right hand side is confusing. Show the link titles at all times, not just when the cursor hovers over the link. (also check that other aspects of the tutorial work well on devices where you can’t hover over page elements).
  • As with the above issue, explicitly label the slide tabs along the bottom (less of an issue though).
  • Separate out core CommonMark tutorials from extension tutorials (such as on the tutorial on tables). Perhaps just remove the extension tutorials for the time being?
  • The site appears to be responsive, but only to a point. Make the tutorial layout look good on mobile devices.
1 Like

I think instead of removing them entirely, you might want to make them links that lead offsite to the tabs on The Markdown Tutorial . While I agree learn.commonmark.org should focus on commonmark specifically, I think the reference to other markdown flavors is still useful, at least while those flavors are still commonly used.

1 Like

A few additional improvement suggestions:

  • At first I didn’t see the “Start” button, or more likely unconsciously assumed it would you scroll down to the “Reference” section. So, I propose to rename the “Start” button to “Start interactive tutorial” and make it larger or more padding…
  • In the tutorial: make the images at least .svgs and choose a font that’s not as stretched and it should be a monospace font. Or better yet, instead of using images use accessible html text that can be copied, marked to see where are how many spaces etc.
1 Like

I moved it here with some tweaks

http://commonmark.org/help/

Lots of work to do, I wish I had noticed @eh3rrera used images for the background elements :cry: but overall, it’s great and I will fold in the above advice.

(and I want to strip all the Reddit and GH references, it’s just too much for a tutorial to teach all that plus site-specific flavors…)

1 Like

Ok, the main page is much better now, simpler, clearer. I have a lot of work to do on the exercises but I am happy with the essential reference page.

I should probably have a “learn more…” link at the very bottom of the main help page for people that want an exhaustive reference. Right now it’s three main things:

  1. The TL;DR 140 character Twitter explanation of “What the heck is Markdown”

  2. Link to 10 minute interactive tutorial for people that want to learn it right now in their browser.

  3. A quick reference card with the essentials for people who want to scan it for 60 seconds and get the general idea of how Markdown basically works.

  4. (not there yet) more depth at the bottom of the reference card for people who reach the end and want even more detail than the quick reference card can provide.

Feel free to use any of the text from these guides if you don’t want to start from scratch: markdown-garden/source/guides at master · chrisalley/markdown-garden · GitHub

1 Like

Ok I added more links at the bottom of the page leading to extra detail of various kinds. Not quite sure how to work in your texts @chrisalley.

I also made sure the reference table works on mobile, pretty clean solution, just suppress the middle “second example” column in the table, switching it from 3 columns to 2. That looks good on my iPhone 6+ and seems OK in the Chrome mobile emulator for smaller devices.

http://commonmark.org/help/

Still have not had time to completely rework the tutorials but I will try to get to it before 2016 here.

The tutorial doesn’t look good. It looks great!

However, it has a couple of minor issues:

  1. Strikethrough’s gone :+1: but that left broken links in navigation (both menu and next/prev).

  2. Menu rendering on mobile Chrome is buggy (at least on my Android 5.1): parts of the page show on top and bottom of screen, trying to scroll the menu randomly scrolls the page etc.

Otherwise, great stuff.

1 Like
  • I fixed the missing navigation issue between the lessons, but I still haven’t decided on the final structure. We may add or remove some lessons in there, or steps in the lessons, as we go.

  • I made the lesson numbers proper HTML/CSS elements rather than images.

  • I am torn on making the lesson intro text example, with the superimposed red + symbols, HTML – I think I’ll be in alignment hell if I do that, as trying to get those red + symbols to be in the exact right place will depend on the proper font and rendering in the browser. I’m thinking I’ll just re-render the text at a much higher resolution in Roboto Monospace. I may give it a shot, just because rendering text as images is such a PITA and makes the lessons harder to change, edit, and improve.

It does seem like a proper intro for each lesson section takes the form of:

  1. Here’s what we want to do (make something bold or italic)
  2. Here’s the particular keyboard characters we will use (* and _)

And the individual tasks within each lesson should be of the general form

  1. Super simple example (make this word bold)
  2. Slightly more complex example (make this word bold and that word italic)
  3. Full complexity example (make words both bold and italic at the same time)
  4. Playtime, which will mention the special cases (how do you escape an asterisk, etc)

How about embedding the text as SVG? That won’t solve the editing problem, but at least it would supposedly scale better.

Good news!

I was able to replace the final set of images with text, so it is much easier to update each lesson now, and there’s less to send over the wire.

I need to majorly tweak the individual exercises in each lesson, but I feel the general structure of the help pages are pretty solid now.

http://commonmark.org/help/

It’s looking good @codinghorror.

Would it be possible to make the content width resize on mobile based on the screen width? As you can see in this screenshot, the right padding is a bit off.

What device is that? I am looking at the iPhone 5 emulator and it doesn’t appear that way?

It’s an iPhone 5c - I took the screenshot on an actual (non-emulated) device.

Ok I think that was fixed by generally tightening overall space on mobile (read: media query for minimum browser width)

1 Like

It looks much better now.

Would it be possible to bottom-dock the tooltips for mobile users? Requiring a tap on the screen’s top to close a tooltip opened by a tap on the screen’s bottom doesn’t seem very friendly.

Now, make the scrollbars autohide, and it’s perfect :sunglasses:

I think you can tap anywhere to close the expanded areas on mobile, at least that’s the way it works for me in the Chrome mobile emulator.