Toward a Better Markdown Tutorial

blog
24

I’ve seen a lot of tutorials, lots of effort to push the masses to markdown. I’ve done it too where everyone in my immediate online social circle has a curmudgeon’s affinity for bbcode simply because it is what they are used to.

The basic gist my mind has compiled from all the various responses I got when trying to introduce markdown boils down to “This is IT stuff for coding geeks? Then I don’t want to learn, it’s probably complicated.”

Every. Single. Response.

While it was not outright explicit as mentioned above, all made reference in some way overall to my background as a “coding geek” (air quotes), web developer and system administrator.

“I, with my superiority to all that is efficient, think that you, the web pleb and consumer, should use this system for max efficiency for my systems and my fellow admins and developers.”

This air is something I see every time I try to introduce something from the world of IT and power web-users into the ‘mundane’ circles. Markdown is no different. GitHub was worse.

I used to do a lot of ALLCAPS for emphasis. I have to when I roleplay on a MU* (an offshoot of telnet and dial-in BBS). However when I did that I noticed others saw it as ‘melodramatic’, especially when it came down to creative writing (i.e. roleplay). Bold or italicized writing does the same thing but allows the reader’s mind to process it in a different way. I liken it to some kind of instinctual context. A sense of eloquence like reading a book all neatly presented versus the screaming of some preteen and they HATE EVERYTHING I JUST WISH THEY WOULD STOP. GOD! It is a context that is nigh instinctual even though Humans weren’t born to enjoy the extra padding and presence of a bold word phrase versus SOMETHING BIGGER BUT MAYBE NOT. It doesn’t matter what I’m writing about but I can say for certain formatted text online shows that the person writing has a sense of integrity in a (online) world where there’s an uneasy sense of ‘should I care how I present myself here?’

It’s the exact same reason writers of all stripes don’t use ALLCAPS. It’s writing 101, especially from the likes of Elements of Style and nearly every other writing book and grammar guide out there.

ALLCAPS is not the best solution to the problem of needing emphasis, unless if one does not care what their readers think of them.

(Bonus: some of us ended up using markdown in MU* roleplay. While it may have looked odd in a telnet environment it did however show up when loading the .txt logs into a markdown-compatible browser or viewer. The writing lit up with wonderful formatting. It beats having the client output everything in messy HTML. )

That is the nugget of wisdom from your entire response. One can’t go against Human Nature. Work with it, exploit it if need be for these benevolent means.

A person learns by doing it In natura and with a cerebral reward to push conditioning. I know when I always click the heart to register a ‘like’ on a Discourse site I get a positive mental response by just seeing the heart ‘beat’. When my mind got some positive feedback then it was easier for me to understand why it’s important to use Discourse’s likes and everything went from there.

The one thing I noticed that works in similar ways to a like’s ‘heartbeat’ is to have a markdown-compatible text area format the text as the user formatted it with correct markdown. It is a hybrid of WYSIWYG and markdown. It is immediate and instant gratification. I noticed some of those I tried teaching also hated the ‘two pane’ view as seen here on Discourse’s composer drawer and Ghost’s backend. But I also saw that the person I was teaching took well to StackEdit. To a point she was actually having a bit of fun. I noticed that she was using the styling more with markdown. The thing was that 1. she didn’t need to use the two-pane work+preview that she hated and 2. she got immediate gratification for her correct markdown because StackEdit’s ui styles the text in a way that showed her she was correct. I think it was the first time I ‘got through’ to someone who otherwise was really resisting my efforts earlier.

MarkdownPad does this too, much to my pleasure. But StackEdit does it where it has more ‘style’ and more weight. It looks nice, it makes someone feel good. That’s what is desired.

Because I believe the only way to learn is to do it ‘in the wild’ and condition a user to enjoy using it I won’t submit a tutorial for this contest, even though that keyboard is calling my name. But I still wanted to contribute in some way so I decided to take the plunge, sign in and offer my input and observation based on past efforts.

25

TL;DR Here’s my proposition which is quite modest and minimalistic. Nothing interactive, but only a simple cheat sheet, easy to understand at first sight.

Note: The “Ghost editor” help page is great but :

  • The 3rd column with key Shortcuts are too much distractive/frightening. For a newbie, at first look, it should be as minimalistic / as simple as possible. This 3rd column of key shortcuts
    adds some more mystery for the newcomer

  • It’s written H1, H2 but not bigger than normal text. => it’s impossible to imagine quickly what it’s about

  • It’s written “Image”, but with no image => impossible to imagine quickly what it’s about…

1 Like
26

Here’s my entry to the contest. And here’s the code. Besides the basic markdown syntax, I cover Github and Reddit extensions.

The site has two sections. The first is a reference sheet for the three versions covered. The second is the interactive tutorial. It’s heavily based on Garen Torikian’s tutorial, adding a few things and putting it together with a bunch of jquery plugins to speed up development. There’s a challenge at the end of the tutorial that now that I see it I don’t know if I got it right. Anyway, I hope it helps someone, any kind of feedback is welcome.

2 Likes
27

Excellent! I’ll be reviewing all the entries by the end of next week. There’s still time if anyone wants to enter the contest!

28

Interactive tutorials are cool (such as the one from @eh3rrera), but really, don’t you think it’s just too much?

Do we need to spend 10 long minutes (that’s what we expect when being here in such a tutorial when we discover that there is at least 16 steps in the vertical progression bar and 4 steps in the horizontal one!) for an interactive tutorial ?

I think that expecting a user to stop what he’s doing, to start a funny tutorial is not really great user experience.

Did we need an interactive tutorial when we first used MS Word to know how to put things in bold or italic? Even on MS Word for DOS (yeah!), I clearly remember it was straightforward (no tutorial needed) that we had to go to menu “Format”. Period.

TL;DR :

  • Interactive tutorials for learning how to code a whole new programming language? Yes, maybe.
  • Interactive tutorial for learning just a few tricks that can be understood in a blink by looking at a cheat sheet that can fit in a half screen? No!
    It would make the whole thing more complex than it actually is!

We shouldn’t forget Markup language is just how to use ~ 10 special characters *, **, [], it’s not like learning a language with special keywords and a specific grammar, etc.

1 Like
29

As someone who just recently learned Markdown, I think there is a more critical issue here than learning the code itself, which is blindingly simple:

(I’m kind of embarrassed to admit this, but:) I’ve been lurking around forums my entire life, including using Markdown, and it was not until I took a formal class on git and GitHub that I realized that Markdown was a formal language, and that it was the same on so many forums. Somehow I managed to learn how to markup my posts on half a dozen different sites, without realizing it was the same markup language, and so I never bothered to learn it in detail because I figured I’d just have to relearn it on the next forum.

I blame it on growing up in a time when most forums were hand-coded and every page was different (and mostly sucked). My wife also discovered forums in the days when they were all formatted like email chains, and she still refuses to go to any website that calls itself a forum. I guess what I’m saying is that I think this could usefully be expanded not just into a tutorial on Markdown, but a tutorial on forums in general, as a larger concept.

30

At the beginning, I was thinking the same! I found Creating Content with Markdown: Learn by Video, an hour-long video about Markdown, and I thought “An hour-long video? How can someone talk an hour about something so simple?” But after learning more about Markdown, I found it has a lot of subtleties and the fact that there are many implementations and extensions doesn’t help in any way to its simplicity.
So I decided to err on the “too much” side. I tried to view this project with a really beginner person in mind, who wants to know everything about Markdown, who has a lot of questions and wants to try a lot, not just understand. I don’t know if such a person exists or want to use a (long) tutorial, but why not have that flexibility? For example, my tutorial doesn’t force you to go through all its steps, you can explore or skip all you want.
That’s why in my opinion, Markdown does deserve an interactive tutorial.

1 Like
31

It depends:

  • If the target is an intermediate user who wants to know more about Markdown, then it’s excellent to have such a detailed tutorial and/or a one-hour-long video to really master all the subtilities of the language.

  • If the target is a beginner who sees Markdown for the first time, then, no, I personnally think it’s not a good idea to see “Tutorial here with 16 steps”. Of course, as you said, a user can skip steps. But what’s the result? Frustration and shame!
    In fact, skipping the tutorial after a few steps creates this pyschologic effect on the learner :
    "Huh, there was 16 steps, but I skipped them, me, lazy learner!"
    and then it lets the learner think it is really something complicated.

If you give too much informations as “first contact ever with Markdown”, there’s a risk of overfeeding.

Do we really need more than “italic, bold, code, link, image, and list” during the first weeks of use of Markdown? No!

We shouldn’t frighten the learners and make them think it’s complicated with a multi-page tutorial.

Joseph

32

Here is my entry to the contest.

And the code is here. I covered the basic markdown syntax as well as a couple of advanced tracks (nested loops, code formatting). The interactive tutorial is very simple and the lessons light up in green when completed.

I hope this is of use to someone.

1 Like
33

OK! I apologize, I am a little behind here but should start evaluating the entries soon!

edit: judging is now beginning, @pkarthikr @eh3rrera @JosephErnest I added your entries here

1 Like
34

I wrote a markdown editor tool, here’s the live demo: http://juliusakula.github.io/editor/#/

I link to a markdown cheatsheet and source code in the demo.

here’s the tutorial of how I created the tool (tutorial is on tool creation, not markdown itself): https://www.airpair.com/javascript/posts/from-apprentice-to-journeyman-web-dev <- airpair posts are also written in markdown!

@JuicetinMurdock on twitter

35

So is there something wrong with referring people to the standard http://daringfireball.net/projects/markdown/ as most websites currently do?

For sometime before I had to use markdown within my own code, I resisted learning about markdown… and got a long just fine! But when I did find the need to learn about it, I had the will to read through the information at daringfireball and found it to be a perfectly fine introduction and set of documentation.

36

Winners have been selected, finally :sweat_smile: See the topic here for results: