It's always surprised me when people, especially technical people, say they don't know Markdown. Do you not use GitHub? Stack Overflow? Reddit?
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.
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.
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ā noreply@codinghorror.com
wrote:
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 
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.
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.
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
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.
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?