Toward a Better Markdown Tutorial

It's always surprised me when people, especially technical people, say they don't know Markdown. Do you not use GitHub? Stack Overflow? Reddit?

This is a companion discussion topic for the original entry at

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.


That’s pretty emphatic, tom, but you’ve got a point. I’m not sure accessibility is the most important thing to strive for though. After all, if I can only use it on one or two sites I actually visit and I post on those sites only rarely why spend even 30 seconds trying to figure out the “advanced” features (and almost everything beyond entering plain text is an advanced feature at that level of engagement)?

I agree also that Tom has a point, but at the same time, nobody HAS to use Markdown to start participating. In this sense there is no barrier to entry. And all the buttons are there in the editor if needs be.

I’m not sure that the basics of markdown are even complicated enough to merit a tutorial. I’d have thought a simple explanatory text, containing the main aspects of markdown, with source on the left, result on the right, would be ample. Then a link to ‘advanced’ and you’re done.

1 Like

And the advanced features of markdown (like code blocks in list items) are cludgy and hard to remember. This reminds me of why I never use tutorials anymore, except as limited reference material if nothing better is available: They pretend to cater to the individual, ignoring the fact that everyone has a completely different mental model from everyone else. Tutorials require either hard AI or an actual person to adjust the mental model effectively and efficiently. The result is that even good web tutorials end up boring and slow, because they must cover material which everyone but the complete newbie already know.

That image you posted of the Ghost editor reference card looks great to me, it tells you exactly what you need to know without any useless fluff and if you really need more advanced information it contains a link for just such the occasion (presumably the information at the other end of the link is also useful but I have no idea where it leads ofc). With the buttons above this text input area and the live preview to the right, having such a reference card available somewhere (implementation is irrelevant for the purposes of this post) would be perfect imo. Why do you say it’s only “OK”?

I apologize for being too emphatic, but I’ve noticed a lot of time wasted
on things which are cool, useful, and even fun, but they don’t get used and
require a lot of effort, borh on the design amd underlying code. I’ve not
done “great” tutorials for vim and javascript amd I use them constantly.

It might take far less effort to create a markdowm “ribbon” or other UI
element than it would the tutorial. And it would be immediate
gratification for the user. Is it better to spend 100 hours on a tutorial
or 10 on a ribbon?

A tutorial begs the question “What can we do to help users do Markdown
effectively?” If it is the wrong answer, no matter how good a tutorial, it
won’t change anything.

  • What we view as our primary markup format, and what we want people to
    learn to use, is Markdown.*

I would just rewind the leap to the tutorial.

What would make me want to learn Markdown? How about a set of wordpad like
apps, e.g. a mobile app - I hate having to take my fingers away from the
keyboard to select formatting. Even a markpad webapp. If you made
Markdown more useful, people would learn it - naturally and incrementally.
If it isn’t something I use daily, much less hourly, I’m not going to spend
a significant amount of time.

But others might have different and better answers to “I would learn
markdown if…”.

How many would answer “if only there was a good tutorial”? And nothing
else besides the tutorial - nothing else changed?
On Mar 27, 2015 8:44 PM, “Jonathan_Galliher”

1 Like

one simple Question though why is _this_ not underline , /this/ not italic, *this* not bold.

Edit: and how do I escape these, so you can see, what I mean :wink: it’s underscore, slash & asterisk

But they’re not invisible. You can clearly see something as bolded, italicized, underlined, etc. without tags, because they clearly look that way in the editor. You can see it; therefore, it is by definition not invisible.

I personally don’t like invisible formatting tags

Funny thing is, that exactly why I don’t like markdown and ilk. HTML may be verbose, but its lexical syntax is straightforward, and I can write raw HTML fast because it’s simple and regular. Whereas pretend-text formats are a quagmire of rules and exceptions to rules.

I have to say, I really appreciate the semi-WYSIWIG editor I’m writing this in. Mainly because the live preview makes it easy to write markdown the only way that I have ever written it: by trial and error.

So please, direct your efforts towards improving the WYSIWIG stuff, so we can hide the ugliness instead of teaching it.

1 Like

I read this post Friday, and I was very interested because making an interactive tutorial seemed like a lot of fun. Naturally instead of reading the existing tutorials, or even looking at Discourse’s comment system I immediately started hacking…

In my free time on the week-end, I threw this together, the source code is here. There isn’t even any (published) tutorial bits yet, just the basics of a markdown editor, which functions like a non-wysiwyg version of this page, and a lot of really bad CSS.

I lack the design skills to make this into a “better markdown” tutorial, but maybe other people can build on it, or laugh at my efforts. Either way I got to do something fun this week-end, and I look forward to more playtime next week-end.

1 Like

Hi Jeff, nice idea the contest for The Markdown tutorial.

I am changing the topic a little. What do you think about current Atlassian Confluence approach?

I’ll post my experience, in the hopes that it gives someone clever an idea…

Honestly, what helped me the most was getting mod privs on a SE stack. Why? Because that allowed me to edit other people’s comments.

Now why did that help? Because that suddenly allowed me to see the markdown content used to generate cool effects in comments (which don’t provide a WYSIWYG editor for doctrinal reasons). Simply being able to put links in my comments was a huge breakthrough. Then there was the time I saw someone else put an endnote on a post1, edited the post to look at the source, and now that one’s in my repertoire as well.

Perhaps a “show source” button of some kind is all that’s needed?

1 - like this

1 Like

That’s fine, you can build that alongside the other vectors – tutorial and reference. “Yes, and…”

Sure, the editor here in discussion has that:

There’s even tooltips that describe what will happen if you click the button, or you can click it to “see what happens”. And of course the editor in discussion has a live preview on the right, which looks like this (expand to see it animate)

It’s true that most basic written communication doesn’t need fancy formatting anyway. Just type. For example, what formatting did your long reply have? I see nothing other than a basic blockquote at the top. No bold, no bullets, no headings…

I think the point is that the “what is Markdown” and tutorial are for people that don’t know anything about text formatting, or markup, or maybe even computers. I remember learning about styles being independent of the document in Microsoft Word in the early 90s and my mind was blown.

I’m just not a fan of sweeping things under the rug. I’ve deleted too many invisible formatting codes and had horrific layout things happen in a document that I could not fix, because everything was invisible.

Could be; I suggest building these experiments to find out!

That’s why I’m proposing these multiple approaches so everyone can find one that fits them, from “I barely touch computers” to “I want to know all the arcane details”.

Well, try using some of those here in this editor. You won’t be getting strikeout… which isn’t part of Markdown proper … and I never start lists with an asterisk, based on that card, you’d think asterisks were required. I am all for a reference card, particularly for an audience that may not know “old school” ASCII conventions from email circa 1995 – but we need to build something more than a mere cheatsheet.

1 Like

Agreed. I grieve that the WordPerfect approach to word processing got displaced by the MS Word approach.

Markdown is another story. Even something as simple as replacing /slashes/ or _underscores_ with italics is a piece of special-case syntax to learn. Just now, I needed literal underscores instead of italics, so it took a few experiments to find out how to do that. I found out that backslash is the escape character. Or maybe it’s not, if I write a\b\c\d it isn’t. The syntax is just so very, very complicated.

Such is the nature of DWIM: you set out to create something simple and automatic and free of rules, and end up with more rules than you can count.

I don’t fit into either of those groups.

[quote=“AndersMunch, post:18, topic:3178”]
I don’t fit into either of those groups.
[/quote]Those are just the ends of the sliding scale, he’s including everything in-between as well with that statement.

Right, but I’m not on the line that connects these two extremes either.

I’m objecting to the idea that someone skilled in computing will necessarily want to know the arcane details of markdown. Overcomplication is bad for everyone, not just novices.

OK, then learn … typing? English? I’m not sure what your point is, here. Formatting isn’t ever required for text, it’s just a nice to have. Whether you need it or not is entirely up to you.

My point is that we want great resources to exist for the people who do want them.

Hey, I do not want to be annoying, but Atlassian is a big company and they are betting to a completely different approach, I mean, invisible markup and wysiwyg.

Are you really sure that a human markup is the future?