I think that the help should be the most clear thing. I'm about to suggest an edit to the Code section in the Markdown Help, because:

  1. It's lacking to mention an imporant feature: how to apply 4 space indent to multiline code. (Either in the short and in the advanced help).
  2. There's one misleading element (the Tab example)

1) Indent four spaces for multiline code

The most important feature: how to indent multiline code, is not mentioned.

While my next suggestion would only change some words, I'd like to add a complete new line.
The new line might be something like:

To indent by four spaces a multiline piece of code, select it and click on the {} button, or use the Ctrl+K shortcut.

(I'm not sure if the shortcut bit should be mentioned in the short help.)

I know that a new line is a major change, but I think that it's worth it.

If, for technical reasons this line can't be added, I would at least like to see it in the advanced help. It should be in the advanced help anyway.

Since the first line of the advanced help reads: "Indent four spaces to create an escaped <pre> <code> block", in my first question I was ending up using the <pre> tag for multiline code, but since there was no highlighting I ended up adding four spaces line by line.

So, I'd really like to have the line suggested above (or something similar) in the advanced help, maybe right after the first example. I don't think this should be a big problem.

Honestly I never used the {} button for multiline code, I discovered the shortcut Ctrl+K by luck in a comment to another question, and used that ever since to edit other questions or my own.

2) Misleading example is misleading

Here's a snapshot of how the markdown help looks:

code section help

The example I'm referring to is:

Press the <Tab> key, then type a $.

As you see the Tab has nothing to do with how to format the code, but since in most editor you can choose between space indentation or tab indentation I think that's misleading to mention it here.

A new user is already facing a lot of new things and may not get that that line is just an example. The only things leading to think that it's an example is the darker background.

I didn't honestly understand the meaning of that line until a couple of days ago, I just put it under "confusing" and skip it every time. I thought that I was probably missing something since English is not my first language or because the $ was somewhat special. (Yes, I did try <Tab> + $ to see if it did something).

I suggest two alternatives:

  • Change Tab with Ctrl or Alt or something like that. (l0b0 made me noticed that <Tab> is actually an HTML tag, so I'd say that this was not an option, but still one reason more to change that line.)
  • Or even better: Cook up a new example that have nothing to do with pressing buttons.
    So nobody could think that he might have to press them to indent his code.

Note: I'm aware that there are a couple of other suggestion about the markdown help, but they didn't address the problem this way. Also note that these were problems that I really faced when I was starting out, and I don't think I was the only one.

  • 2
    Actually, if the Tab key is mentioned it shouldn't be in angle brackets (that's HTML!) but in <kbd>. – l0b0 Mar 28 '12 at 9:27
  • @l0b0: Oh I see... Then it seems that my confusion wasn't ended yet. – Rik Poggi Mar 28 '12 at 9:36
  • I am not clear what pressing tab, and $ would cause. On a Mac, it doesn't have the effect of giving me an inline code span. – kiamlaluno Mar 28 '12 at 10:28
  • @kiamlaluno: That's exactly my point, that example is confusing. – Rik Poggi Mar 29 '12 at 8:59
  • Some are even typing <Tab> some code <Tab> (screen capture) like it's some BBCode or something. – Arjan Apr 28 '12 at 18:38
  • 2
    #2 definitely confused me. I felt stupid when I realized why I was confused, but the help could be clearer. Why not just add the words "For Example" or something? (Also, apologies if this should be an answer instead of comment- I'm new to this whole SO thing.) – Matthew Adams Jun 21 '12 at 2:05

You must log in to answer this question.

Browse other questions tagged .