Toward a Better Markdown Tutorial

What we really need is a great Markdown tutorial and reference page,

I think you have misidentified the problem. Even if there was a “great place”, no one is likely to go there - assuming you aren’t paying them or otherwise rewarding them for doing so.

Markdown is a means to an end. It is not an end in itself. Learning it is not an end in itself, it is a means. But how important is the end and you’ve already pointed out it can be reached via other paths.

I’m not going to spend even 2 minutes on a tutorial that only works on a few sites (that already support things I know like HTML if not menus for adding it to the text). It would be like implementing the full WordStar processor trying to compete with Microsoft Word. Or like suggesting coding in Algol, ForTran, COBOL, APL, PL/1, or Awk instead of C or Python or even Javascript. (And I know Awk. And Latex. And HTML). You could do really good tutorials for those too.

Worse, there are two sample tutorial links. The first has the hated “Lets get started but do absolutely nothing useful on the first page” wizard format. I don’t do tutorials designed to maximize clicks (I’m not sure if they are serving ads or not since I’m using a blocker). I like to see the whole thing at once, especially if I need to revisit it as a reference. The second is merely a github repo and it wasn’t obvious what I had to do to make it a tutorial. If your point is useability, “What NOT to do” might be good if prepended.

Now as I type this, I notice a lot of crap on the screen. There is a box as large as the one I’m typing in suggesting “How about a new picture for your account”. A complete overlay markup reference card (50% transparency) showing exactly what text would look like in a compact form would be welcome. There is also a “preview” next to this which I don’t exactly find useful, at least if the text will wrap. I’m not on my 4k monitor (which I got so I could popup stupid references for obscure things - there is a different flavor for our corporate wiki). Can’t I just cut and paste from Wordpad? (or the GNU equivalent?).

If I could simply look at a box or ribbon somewhere onscreen and instantly see the proper “markdown” for the 90-95% cases, I’d be likely to use it. I won’t do it if I have to overlay it, click, have a popup block my typing or anything else which interrupts my typing. Microsoft’s ribbon and menu doesn’t cover up the text area. The third sigma stuff I might do a popup if I really needed it.

Even if I do the tutorial, how much will I remember anyway? It might be fun, but will I remember that all those strange characters around things do the next day?

Have fun with the contest, but I’d be interested in how many actually do the entire tutorial properly from start to finish doing all the interactive examples correctly.

“You could do fancy formats if you just spend the next N hours…”. I don’t care how entertaining it is. Maybe even better than Mavis Beacon teaches typing. Even if some who already knew Markdown 100% enjoy playing with the tutorial. I’m not going to spend the time. If I want to be entertained there are better games, or my Amazon Prime streaming. If I want to learn, there are dozens of things I want and need to learn that are more important than Markdown.

Name any other site that tries to push users to spend even a good part of an hour learning how to use their site. But that is what you are trying to do with the tutorial. Instead of adapting the site to the user, you are attempting to adapt the user to the site. Apple, or at least Steve Jobs understood this with everything made by the company, even if it was something completely new. Google finds its way through successive approximation. I cannot remember a single product by either that REQUIRED (note how I use allcaps instead of trying to figure out the magic charset) going through a tutorial.

What you need to do is to make Markdown, if not intuitive, immediately accessible, to anyone who is, like me at this moment, typing into a box to write text. If you can do that you won’t need either the tutorial or the reference. If you can’t, few are going to bother with a tutorial or reference.

3 Likes