Update the Markdown help to reflect the modern realities of Stack Exchange 2.0

Question

On technical sites, the Markdown help page rightly begins with guidance on formatting code. But the page is reused on non-technical sites where code formatting is either completely unnecessary or co-opted for other purposes such as poetry and poor-man's tables. That means that the average person on a site that's geared toward people that don't intuitively understand Markdown code (or any sort of code at all) and who are in the most need of help, start reading the least-useful bit of help imaginable. That ought not be.

What changes should be made to the Markdown help page to reflect the increasingly diverse nature of the Stack Exchange network?

Answer 1

The Markdown formatting page has been updated for a while to not start with code and preformatted text tips on non-technical sites.

Additionally, there's a new page in the Help Center which, for technical sites, emphasizes the code formatting (using most of the suggestions here), and for non-technical sites, omits any mention of it. This page links to the more detailed Markdown formatting page that is also linked from the ask question page. (It is technically pretty complicated to just move the detailed Markdown formatting page into the help center as is.)

Answer 2

NOTE: This was moved from a question specifically about the code section.

TL;DR: I think there is more wrong with that section than just the code sample. I suggest breaking it out into two sections and expanding them: Code Block, Inline Code.

The code markdown section is easily the most important one on the page as nearly every question and answer contains code and many new users don't format it properly. Despite that, it's the smallest section with the least amount of info visible (without expanding). More space is given to Spoilers.

Add more info to the non-expanded (renamed) Code Block section and create a new non-expandable Inline Code section with the current Code Span content.

Also, I've used a simple and boring code sample for the code block. Almost every other example on that page is meta and gives more information about what is happening -- information that is useful. For the inline code sample, I used something other than keyboard keys, since there is a better way to do that already (<kbd>).

Code Block (not expanded):

By mentioning prettifying, we give someone a compelling reason to want to format their code: it will look better! Also, by mentioning the keyboard shortcut we let them know it's not as tedious to get there as it might seem if they have more than just a few lines of code.

Code Block (expanded):

Inline Code:

I removed two lines from the existing Code Span section. Unless I'm misunderstanding this, I don't think this is true (anymore?). HTML doesn't need to be escaped:

And HTML works just fine (in that you can put it in there), so this is somewhat confusing (although I know what it means). It would be better to use the same language as the code block and say it will be ignored:

Answer 3

At a minimum, the sections should be re-arranged something like this:

Simple blockquotes
Italics and Bold
Links
Comment formatting
Simple lists
Headers
Horizontal Rules
Linebreaks
Advanced blockquotes
Advanced lists
Images
Spoilers
Bare URLs
Tags
Code and Preformatted Text
Inline HTML
Need More Detail?

---

Some things to remember:

• The division between "official Markdown" and the Stack Exchange additions is unimportant to folks who may never see Markdown used elsewhere.

• Blockquotes are the single most important feature of Markdown for many non-coding sites. When I moved from Stack Overflow to Philosophy, I learned to get out of the habit of using codeblocks and into the habit of using blockquotes. (I was learned [sic] forcibly, but kindly, by veteran users.)

• The "Italics and Bold" section should really include some advice on how to use those features. Without that advice, I'd move the section way down on the list as those features are overused. Remove the bold/italic combination too unless there's some guidance on how to use it.

• Links are really important too, since we often ask users to cite sources. The help about links is probably overkill for almost everyone. The post UI does a fine job of helping users link to in text. But the [basic links](http://example.com) form is necessary groundwork for comment formatting, which is pretty useful to know about. (Honestly, some of our users just post bare URLs, which works just fine. Maybe this section should be moved even further down.)

• It's rare to find anyone using or needing the "Advanced" features (nesting lists and quotes). I don't think they are important enough to group with the basic versions of the features.

• Perhaps more important than the commands themselves is guidance about when to use (or refrain from using) the various features. Some sites may want to create their own Style Guides. It would be lovely if new users were able to find such guides at the time of editing rather than after they've posted and had their hand slapped for formatting failure.

• No help page can be a substitute for taking great contributors who are clueless about code and either:

  1. Teaching them how to format effectively or
  2. editing their posts for them.

  On Stack Overflow, this would be madness. But it may be necessary for some users on some non-coding sites.

Conclusion

Non-code-intensive sites should not lead off with "Code and Preformatted Text" in their editing help page.