53

I think we should be revisiting the official Markdown Editing Help document. I think it's rather impenetrable for people unfamiliar with Markdown. It's terse and sports unnecessarily confusing in-jokes:

Indent four spaces to create an escaped <code><pre> <code></code> block

What's an "an escaped <pre> <code> block"? Why do I need this? This is inside HTML jargon, which is a bad explanation for the task at hand. The example is also shown as both its source code and its own result in one. The code block's contents are unnecessarily punny and distracting.

enter image description here

Again, what, why, who? Why would I hate this if not what? The explanation is too tongue-in-cheeky and obtuse. The explanation might work for people who understand HTML, but that doesn't necessarily even cover all programmers, much less users of other entirely non-programming related SE sites.

Now, compare this with the excellent official FAQ: How do I format my code blocks? This is much more straight forward, in detail, understandable, and practical. Yet it's not what's linked from the ? button inside the editor and is hard to discover.

7
  • 5
    Accept this as a further indication of my support for this excellent suggestion and the way it is presented. I really, really, really, dislike that "help". I wanted to superscript something the other day. Not only could I not discover that (not a killer at the end of the day) but I almost felt like I had been given accidental access to the rules for a (young) teenage-"geek"'s clubhouse. May 28, 2015 at 8:45
  • 9
    @Bill: 'young'? My experience is many programmers' in-jokes can actually only be understood by those of Sufficiently Advanced Age. I'd regard both 'blink' and '42' as such. Another example, from CodeProject's Daily News: 'Giraffes can be dangerous. "A moose once bit my sister..."'
    – Jongware
    May 28, 2015 at 9:02
  • @Jongware No matter the age of the author and those who feel happily bound to the content, my perception is as I stated :-) May 28, 2015 at 9:21
  • 6
    I think the new explanation, if there were one, should do side-by-side comparison of Markdown input and HTML output.
    – user3373470
    May 28, 2015 at 14:42
  • 6
    Yeah, I've always hated directing people to that page for reference on formatting code. I think it should refer to four spaces and to the editor shortcuts (CTRL+K and the button at the top) and give very little emphasis to html alternatives and terminology ("span" and "block"). Toss 'em in a separate collapsible, like "advanced code formatting", along with code in comments, language prettifying and whatever else is not needed by most new users.
    – Frank
    May 28, 2015 at 15:10
  • 5
    The 42 joke was the result of an attempt to replace the terrible old text.
    – Brad Koch
    May 28, 2015 at 21:22
  • @humble.rumble If by "blocks" you mean the code blocks, then that's thinking too small. Just replacing those with better example code blocks won't improve it a lot. I'd like to hold a contest to rewrite each section of the help.
    – deceze Mod
    May 29, 2015 at 6:29

3 Answers 3

7

I might be the only one, but I actually think the help page is pretty well written. Yes, there are a lot of tongue-in-cheek jokes, but those are all contained in the example blocks themselves (which are clearly a different colour). On top of that the markdown in question is highlighted each time, which further reduces the need to read the full markdown. All of this was not visible in the quotes in the OP, thus making it look a lot worse then it was in my humble opinion, so I edited in screenshots.

Either way, I am inclined to say that if anything the writing style actually makes the document more accessible to new users, as for those who care to fully read the examples it becomes a lot more doable to read the full document. It's not like every example contains a joke or cultural reference, but those that needed filler content at least don't resort to old fashioned lorem ipsum text.

Comparing it to for example the FAQ you linked the FAQ has a lot of valuable information I wouldn't want new users to even know about (func(arg1){ //why is this even possible };...) and I can't imagine anybody reading a long page like that from top to bottom except if they're looking for something (e.g. how to escape backticks in an inline comment). Additionally the examples of the help page are a lot more clearly presented than the FAQ as well. To put it in more normal terms: One is a getting started guide whilst the other is more like a reference, and the language and style used perfectly fits a getting started guide in my opinion.

11
  • 2
    While I generally agree, I do think the FAQ could be easier to find. I didn't know it existed until now. Perhaps the help page could link to it? Currently it has a link to daringfireball.net, which is less than helpful since we've got our own Markdown flavor.
    – Kevin
    May 29, 2015 at 2:40
  • 2
    I disagree. Yes, it's a nice short cheatsheet, but not an editing help that would practically help newcomers a lot. Yes, the FAQ is too in-depth at points, and that content can be put at a further second level. To be practical, the editing help should contain language that doesn't presuppose knowledge of HTML and it should explain the use of the editor buttons to format content. It severely falls down in both areas at the moment.
    – deceze Mod
    May 29, 2015 at 6:25
  • @deceze You don't need to know HTML and if you need to provide code samples I do believe HTML (or even just XML) and C are quite sensible choices. At least better than "code goes here". I do fully agree that explaining the buttons in the editor would be good (though it should probably have been a seperate post)... though then again, I wonder how many users have issues with that (those users too lazy to check the buttons aren't going to read the help, those users that do care about formatting their post are likely to figure out the buttons). May 29, 2015 at 12:52
  • You don't need to know HTML to provide code samples, but you pretty much need to know HTML to understand what the editing help page is trying to tell you. Its language is skewed towards people with HTML knowledge, and IMO is pretty impenetrable to everyone else. I would think that some people may click the ? button before they click any of the other buttons, but that button simply doesn't lead to very comprehensible help. I'm saying we need to look at the flow an HTML-illiterate person will encounter when confronted with the editor the first time, and at the moment it's pretty unwelcoming.
    – deceze Mod
    May 29, 2015 at 13:01
  • @deceze As you mentioned the HTML-part right after complaining about the tongue-in-cheekyness I assumed you were discussing things like the use of <blink> in the code sample. If actually you mean the text should just say 'to create an escape code block' then I fully agree with that part, though I am also fine with 'to create an escape <code> block', but for non HTML users the mention of the <pre> tag would indeed be confusing. May 29, 2015 at 13:15
  • It's really a combination of everything. That document should explain how I can format my post so it appears nicely on the SO website. Let's say I'm an ASM developer and know nothing about HTML. That document explains to me how to do something to achieve some HTML result (...!?), uses code samples which I'm not sure are input or output (they're both in one) and uses sample code which I'm not sure I'm supposed to find funny or get some additional information from.
    – deceze Mod
    May 29, 2015 at 13:23
  • @deceze The criticisms against the jokes in the code samples are as far as I can see totally out of place as the highlighting already ensures a clear differentiation is made between 'the important stuff' and 'the filler', but as I said I do agree with you that the text itself could be improved by referencing less HTML and putting the markdown and output side by side. May 29, 2015 at 13:30
  • 1
    Hmm, yeah, the printf isn't so bad, but the second choice of an HTML tag inside the sample when I'm already confused about HTML and whether I'm supposed to use tags or not is unnecessary IMO. I'd simply stick with bland irrelevant C-like code, which pretty much everybody gets.
    – deceze Mod
    May 29, 2015 at 13:33
  • @deceze Nowadays I think more people will understand the html joke than the printf joke. And the way code samples from C, HTML, Javascript, .net and English literature are used make it feel kinda welcoming to everyone to me. Maybe some kind of binary joke should be added still somewhere and it really would cover all bases :) . Either way, been reading through some markdown guides, and yeah, we should simply drop all the HTML in the explanations. And damn, I just found out that Github has tables in it's markdown flavour :O Please let us have those too!!!! :O May 29, 2015 at 13:41
  • Hmm, I don't know. <blink>? Nobody's really used that in ages. That joke becomes more dated and obscure by the minute... ;) – Sure, it doesn't have to be all business like, but clarity should come before being cutesy.
    – deceze Mod
    May 29, 2015 at 13:45
  • @deceze As long as you know any XML you can figure out that whatever is in between the blink tag is probably gonna... drum roll... blink! And if you don't that's no big deal. Oh well, do have to say that with the neat highlighting and stuff actually the stackoverflow guide is still one of the better ones out there. Just all the HTML in the explanations makes it quite a mess. May 29, 2015 at 13:48
4

Here's a sample draft of how I think the editing help page should read:


Editing help

Stack Overflow uses CommonMark* to format text. Follow a few simple rules to have your post appear well formatted:

Code samples

To have code samples appear correctly and readable, you will want to preserve any line breaks and indentation it has and display it in a monospaced font. To do this, indent it by four spaces at the beginning of the line:

Write:

Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

    var foo = bar(function () {
        return baz();
    });

Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris
nisi ut aliquip ex ea commodo consequat.

to get:

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

var foo = bar(function () {
    return baz();
});

Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

(This should be displayed side by side, with the source on the left and the result on the right, indentation appropriately highlighted to draw attention.)

To automatically indent a block of text by four spaces, select it and click the {} button in the toolbar. You can also use the keyboard shortcut Ctrl+K to do this.

code blocking icon properly highlighted

To highlight code inside a paragraph and display it in a more distinctive monospaced font, use backticks (`).

Write:

Lorem ipsum dolor sit amet, `function foo() { bar(); }`, consecteur adipiscing elit.

to get:

Lorem ipsum dolor sit amet, function foo() { bar(); }, consecteur adipiscing elit.

(Again, side by side.)

You can, again, use the {} toolbar button or the keyboard shortbut Ctrl+K for this.

For more in-depth help on formatting code blocks, see advanced code formatting.

Linebreaks

(More such explanation here...)


* Or whatever flavour and naming of Markdown is preferred these days.

-24

What's an "an escaped <pre> <code> block"? Why do I need this? This is inside HTML jargon, which is a bad explanation for the task at hand.

The task at hand is generating HTML. That is what Markdown is for. If you don't want to work with HTML, either stick to plain text or don't publish on the web.

Some of the examples on that help page are, perhaps, a bit cute. Maybe they could be cleaned up. But the explanation must remain in terms of HTML. HTML is real. It is what your browser understands. Markdown is a light abstraction over HTML. If we seriously believe "the end user should not know or care about HTML," we should switch to a WYSIWYG editor. Markdown is not designed for that use case.

15
  • 11
    100% disagree. You need to know HTML to do complicated things in browsers. You don't need to know what a <pre> tag does in HTML in order to use Markdown; you just need to know "this markdown thing makes your code look like code". May 29, 2015 at 3:03
  • @Chris: Like it or not, the web is built in HTML. You can't write more than simple one-liners if you don't understand the distinction between (say) span-level and block-level content.
    – Kevin
    May 29, 2015 at 3:04
  • 6
    The task at hand is "format some post at an online forum". Users don't care how the markup language they use is called, or wether it will be used for generating HTML, or what HTML is at all. Users care about a simple introduction to the particular markup language they are supposed to use.
    – Bergi
    May 29, 2015 at 3:05
  • 9
    It's not a "like it or not" scenario. It's "if you think you need to understand HTML to use basic Markdown features, you're way overcomplicating things". As a guy who does know HTML, I don't in any way believe that every user on this site needs to know it in order to communicate effectively. May 29, 2015 at 3:05
  • 5
    To give a parallel, this answer is like saying that you need to understand bit manipulation to use a computer. The reason we use Markdown and not HTML here is to provide an abstraction when writing posts. If you need to know HTML in order to use Markdown, we might as well remove the abstraction layer. May 29, 2015 at 3:07
  • @Chris: Markdown is a light abstraction layer. This is explicitly designed into it (go read the page I linked). If you want a heavy layer, use a WYSIWYG editor. Stack Exchange has chosen the light route, and the help page must reflect that.
    – Kevin
    May 29, 2015 at 3:08
  • 6
    You may not be aware but you're coming across as patronizing ("read the page I linked"). I know what Markdown is. I'm a frequent user of Markdown. I never even think about what HTML it's going to generate. All I think about is what the output will look like, which is the entire point of Markdown on this site. Again, we could just use HTML directly if we didn't want to take advantage of the abstraction. May 29, 2015 at 3:09
  • @Chris: "All I think about is what the output will look like.." -- That doesn't sound like something Gruber would necessarily agree with. But after the whole CommonMark fiasco, I'm not sure we're allowed to be friends with him any more.
    – Kevin
    May 29, 2015 at 3:12
  • 2
    The task of HTML is getting parsed into a DOM tree that a browser can render. That's all what HTML is for. So why do we care about HTML at all? And does every HTML author need to understand the DOM? Hell, if every SO user would understand the whole browser/web stack, then half of SO wouldn't exist.
    – Bergi
    May 29, 2015 at 3:14
  • @Bergi: I suppose they don't need to understand it, but if they do, it would be nice if we could explain things in terms they already understand. Since HTML is the web's lingua franca, it makes the most sense for this purpose.
    – Kevin
    May 29, 2015 at 3:15
  • 6
    @Kevin Only that HTML isn't the web's lingua franca. It's English that we speak, not HTML. Most people who use the web ("internet") these days don't understand how it works. Yes, you could explain Markdown in terms of HTML for those who do, but that's not the target audience of SO's help center.
    – Bergi
    May 29, 2015 at 3:20
  • 7
    Why does someone who writes C need to know HTML in order to declare a preformatted block of text?
    – user4639281
    May 29, 2015 at 4:22
  • I have absolutely no idea what a <pre> tag does, and I can use Stack Exchange just fine.
    – NobodyNada
    May 29, 2015 at 4:29
  • 3
    Direct from the second paragraph off of your link: "The idea [of Markdown] is not to create a syntax that makes it easier to insert HTML tags." (emphasis his)
    – Dan Getz
    May 29, 2015 at 5:33
  • 4
    We can do even better with the first paragraph from that link: "Markdown’s syntax is intended for one purpose: to be used as a format for writing for the web." Which perfectly summarises the issue I have with the current help and contradicts your point: the task at hand is to write for the web, not to generate HTML. People should not have to learn about HTML when all they want to do is write for the web.
    – deceze Mod
    May 29, 2015 at 8:15

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .