# Feedback on our interactive Markdown tutorial
**URL:** https://meta.discourse.org/t/feedback-on-our-interactive-markdown-tutorial/37290
**Category:** Site feedback
**Created:** [December 30, 2015, 11:48pm UTC](https://meta.discourse.org/t/feedback-on-our-interactive-markdown-tutorial/37290 "2015-12-30T23:48:02Z")
**Posts on this page:** 20
**Page:** 2
### Author:  [@meglio](https://meta.discourse.org/u/meglio)
#### Post date: [December 31, 2015, 8:59am UTC](https://meta.discourse.org/t/feedback-on-our-interactive-markdown-tutorial/37290/26 "2015-12-31T08:59:44Z")
Let’s get it translated and link to it from the Discourse message editor.
---
### Author:  [@jegillikin](https://meta.discourse.org/u/jegillikin)
#### Post date: [December 31, 2015, 12:54pm UTC](https://meta.discourse.org/t/feedback-on-our-interactive-markdown-tutorial/37290/27 "2015-12-31T12:54:34Z")
Feedback: Extremely helpful. I’m transitioning my team (we do book and lit-journal publishing) from screwing around with Word documents by email, to using Markdown files committed to a local SVN repository. Many of them don’t quite get the concept, so having both a quick reference _and_ a tutorial … well, I’ve already sent them the link. 🙂
---
### Author:  [@codinghorror](https://meta.discourse.org/u/codinghorror)
#### Post date: [January 1, 2016, 10:16am UTC](https://meta.discourse.org/t/feedback-on-our-interactive-markdown-tutorial/37290/28 "2016-01-01T10:16:44Z")
> [@cpradio](#):
>
> So the only suggestion I have, is to make it easier to get back to the original text
This was a very common request across all the sites I asked for feedback on the tutorial.
I’ve added a reset button which is initially hidden, to avoid page clutter, but appears dynamically when the editor no longer matches the initial page load text.
(also @Nick I was able to get the side nav visible on lesson starts which helps a lot, I think)
If you haven’t tried it yet, try it again. I added a little fun 🎉 at the end.
---
### Author:  [@erlend\_sh](https://meta.discourse.org/u/erlend_sh)
#### Post date: [January 1, 2016, 2:25pm UTC](https://meta.discourse.org/t/feedback-on-our-interactive-markdown-tutorial/37290/29 "2016-01-01T14:25:30Z")
> [@mcwumbly](#):
>
> 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.
I also ran into this and suggested a different mitigation tactic:
> **[CommonMark tutorial / help page feedback](https://talk.commonmark.org/t/commonmark-tutorial-help-page-feedback/1267/24?u=erlend_sh)**
>
> 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...
But the root of the problem is really, as you say, that we don’t expect escaping to come up at this point. At first I thought maybe escaping ought to have a section of its own, but on second thought that sounds like a bit much. But I do think the reader needs to be warned, like “heads up! small digression incoming”.
---
### Author:  [@mcwumbly](https://meta.discourse.org/u/mcwumbly)
#### Post date: [January 1, 2016, 3:24pm UTC](https://meta.discourse.org/t/feedback-on-our-interactive-markdown-tutorial/37290/30 "2016-01-01T15:24:21Z")
> [@erlend\_sh](#):
>
> the root of the problem is really, as you say, that we don’t expect escaping to come up at this point.
I think escaping _is_ actually expected at this point. I just only expect to be escaping unintended _emphasis_ based on what I’ve been told at that point.
Currently, the example comes at me like:
1. Apply `style x` to your text using `character a`
2. Escape `character a` to avoid applying `style y`
(wait I thought we were talking about `style x`, why are we talking about `style y`?
Things would flow more naturally to me if they followed this format:
1. Apply `style x` to your text using `character a`
2. Escape `character a` to avoid applying `style x`.
Sticking to this formula for the escaping examples that are spread throughout the tutorial helps make them more relevant, and associates the value they have as formatting characters when that _is_ the intention alongside how to escape that formatting when its unintended.
Separately, and _additionally_ I think a short overview section could be added toward the beginning that does introduce escaping more generically:
1. Overview (first section)
- markdown is awesome, here’s an example showing all the awesomeness
- and it just stays out of the way when you just want to type some normal paragraph
- but if it does get in the way on occasion, you can get around it easily
draft:
* * *
Overview
1. One of the great things about markdown is that it lets you type text which looks just as good formatted as plain text as it does when it is rendered as HTML. Here’s an example of a post written in markdown shown as plain text and HTML:
`insert some long-ish example demonstrating multiple features`
Next
2. Often, all you really want to type is unformatted text anyway. That basically looks the same in plain text and HTML without doing anything special:
`insert some medium example of a normal paragraph of text shown`
Next
3. In the rare case that markdown’s formatting rules get applied when you don’t want them to be, you can put a `\` before the special character to escape that formatting. Try escaping the - below in the signature so it doesn’t look like a list item:
`OK, let's get started!`
``
`- Dave`
Next
* * *
I know CommonMark has put a fair bit of effort into making a few things more intuitive and less error-prone where it doesn’t deviate too much from the existing implementations. For instance, you can start a bullet list immediately after a paragraph with no blank like between them. But if there are still a number of examples that could justify a separate “common mistakes and how to avoid them” section, I think that could go at the end too.
---
### Author:  [@codinghorror](https://meta.discourse.org/u/codinghorror)
#### Post date: [January 1, 2016, 3:37pm UTC](https://meta.discourse.org/t/feedback-on-our-interactive-markdown-tutorial/37290/31 "2016-01-01T15:37:55Z")
> [@mcwumbly](#):
>
> Escape character a to avoid applying style y
I read it more as
> escape `character a` when you really want `character a` to appear verbatim
Each lesson introduces specific character sets, e.g.
- Bold and Italic need \* and \_
- Blockquote needs \>
etc
---
### Author:  [@mcwumbly](https://meta.discourse.org/u/mcwumbly)
#### Post date: [January 1, 2016, 3:55pm UTC](https://meta.discourse.org/t/feedback-on-our-interactive-markdown-tutorial/37290/32 "2016-01-01T15:55:26Z")
Well I’ve done my best but I think @erlend_sh’s [suggestion](http://talk.commonmark.org/t/commonmark-tutorial-help-page-feedback/1267/24) for that page is an improvement if you’re open to a smaller change for those of us who do find it confusing.
---
### Author:  [@cpradio](https://meta.discourse.org/u/cpradio)
#### Post date: [January 1, 2016, 4:15pm UTC](https://meta.discourse.org/t/feedback-on-our-interactive-markdown-tutorial/37290/33 "2016-01-01T16:15:43Z")
Menu of tutorials disappear on mobile android chrome
Steps
1. Visit site, start tutorial
2. Note menu shows properly
3. Click begin lesson
4. Menu still shows
5. Click try it
6. Menu disappears
7. Click back to Emphasis button
8. Menu still not visible
9. Refresh page, menu visible again
10. Repeat steps 3 through 9
---
### Author:  [@codinghorror](https://meta.discourse.org/u/codinghorror)
#### Post date: [January 1, 2016, 10:25pm UTC](https://meta.discourse.org/t/feedback-on-our-interactive-markdown-tutorial/37290/34 "2016-01-01T22:25:31Z")
Yep, I noticed that just before I went to bed – now fixed. It was a side effect of showing/hiding the lesson nav titles on desktop. On touch the lesson titles should always be visible since they only appear on popup.
---
### Author:  [@zopieux](https://meta.discourse.org/u/zopieux)
#### Post date: [January 1, 2016, 11:32pm UTC](https://meta.discourse.org/t/feedback-on-our-interactive-markdown-tutorial/37290/35 "2016-01-01T23:32:47Z")
### Bug report
[http://commonmark.org/help/tutorial/07-code.html](http://commonmark.org/help/tutorial/07-code.html)
1. as asked, transform the table to code but using **a pair of 3-backticks**
2. realize you’ve not followed the statement exactly:
3. indent the code with 4 spaces
4. remove the backtits
5. expect a “success” dialog; be disappointed.
Even though the input is now correct, the success dialog is not triggered. The only way of triggering the success dialog is to _reset_ and indent with 4 spaces right away.
---
### Author:  [@codinghorror](https://meta.discourse.org/u/codinghorror)
#### Post date: [January 1, 2016, 11:48pm UTC](https://meta.discourse.org/t/feedback-on-our-interactive-markdown-tutorial/37290/36 "2016-01-01T23:48:10Z")
Yes, though I would argue you did succeed, you made a code block … success state can only be reached once per exercise 😉
If someone thinks outside the 📦 that’s great.
---
### Author:  [@adopilot](https://meta.discourse.org/u/adopilot)
#### Post date: [January 2, 2016, 12:09am UTC](https://meta.discourse.org/t/feedback-on-our-interactive-markdown-tutorial/37290/37 "2016-01-02T00:09:06Z")
any chances for easy translations into other languages ?
---
### Author:  [@codinghorror](https://meta.discourse.org/u/codinghorror)
#### Post date: [January 2, 2016, 12:10am UTC](https://meta.discourse.org/t/feedback-on-our-interactive-markdown-tutorial/37290/38 "2016-01-02T00:10:04Z")
I definitely want to add something to make translation easier.. any recommendations? It’d be pure JS, no server side
---
### Author:  [@adopilot](https://meta.discourse.org/u/adopilot)
#### Post date: [January 2, 2016, 12:11am UTC](https://meta.discourse.org/t/feedback-on-our-interactive-markdown-tutorial/37290/39 "2016-01-02T00:11:23Z")
it is prity generic maybe you can try using some BOOTS to do translation on fly
---
### Author:  [@riking](https://meta.discourse.org/u/riking)
#### Post date: [January 2, 2016, 1:29am UTC](https://meta.discourse.org/t/feedback-on-our-interactive-markdown-tutorial/37290/40 "2016-01-02T01:29:10Z")
Translation on the fly makes no sense for this, all the text that needs to be translated is static and only changes on ‘updates’. That’s just expending resources for no reason.
---
### Author:  [@pakl](https://meta.discourse.org/u/pakl)
#### Post date: [January 2, 2016, 3:53am UTC](https://meta.discourse.org/t/feedback-on-our-interactive-markdown-tutorial/37290/41 "2016-01-02T03:53:13Z")
Nice idea. I like it.
Some general feedback:
Too much clicking.
Intrusive ‘success’ popup/overlay becomes jarring after a few times.
The step by step structure of the exercises feels a bit dated. I wonder how this would look like as a one-page game where you progress down the page fluidly (ideally by never leaving the input field), rather than having to click through a series of standalone exercises.
Maybe guiding the user through using all of these features in markdown from an empty document would be better than these focused exercises. Just an idea.
---
### Author:  [@codinghorror](https://meta.discourse.org/u/codinghorror)
#### Post date: [January 2, 2016, 4:40am UTC](https://meta.discourse.org/t/feedback-on-our-interactive-markdown-tutorial/37290/42 "2016-01-02T04:40:39Z")
Yeah, there were some entries that had the “everything on one page” layout but we preferred the step by step method for the tutorial. You can look at the two runners up in the contest, linked from this post:
> **[Markdown Tutorial contest feedback](https://talk.commonmark.org/t/markdown-tutorial-contest-feedback/1149/19?u=codinghorror)**
>
> Winners have been selected! First, thanks to everyone who participated – the entries were all of very high quality in my opinion! First Prize 🏆 The Markdown Tutorial by eh3rrera all 16 books in my recommended reading list, or the Amazon value...
One of them is what you are describing, a bunch of stuff on one long scrollable page.
---
### Author:  [@jclifford0251](https://meta.discourse.org/u/jclifford0251)
#### Post date: [January 3, 2016, 2:36pm UTC](https://meta.discourse.org/t/feedback-on-our-interactive-markdown-tutorial/37290/43 "2016-01-03T14:36:32Z")
# Great Job
Loved the tutorial! Here is my feed back:
## Emphasis
> Can you make the whole sentence bold, and italicize the word “must”?
I miss read this and surrounded must with two underscores and a star on each side. I then saw my mistake, highlighted and dragged the underscores to the ends of the line. the app did not register the text change event until i entered a space
## Images
> Don’t bother specifying alt text or title.
expected: leave the alt text blank
## Blockquotes
I mistakenly put a \> in the middle of the line thanks to the word wrap
## Nested Lists
> The content under each numbered item isn’t nested properly. Can you fix it?
directions unclear. I created nested list using an indented dash for each sub item
---
### Author:  [@codinghorror](https://meta.discourse.org/u/codinghorror)
#### Post date: [January 3, 2016, 9:19pm UTC](https://meta.discourse.org/t/feedback-on-our-interactive-markdown-tutorial/37290/44 "2016-01-03T21:19:10Z")
> [@jclifford0251](#):
>
> I then saw my mistake, highlighted and dragged the underscores to the ends of the line
Yeah I don’t think drag events are counted as keydown events.
The last exercise is supposed to be a bit harder, since it is the last one.
---
### Author:  [@codinghorror](https://meta.discourse.org/u/codinghorror)
#### Post date: [January 5, 2016, 1:25pm UTC](https://meta.discourse.org/t/feedback-on-our-interactive-markdown-tutorial/37290/45 "2016-01-05T13:25:33Z")
Ok, [http://commonmark.org](http://commonmark.org) has been updated with a prominent link to the reference and tutorial.
[Previous page](https://meta.discourse.org/t/feedback-on-our-interactive-markdown-tutorial/37290.md?page=1)
[Next page](https://meta.discourse.org/t/feedback-on-our-interactive-markdown-tutorial/37290.md?page=3)