6

In reference to https://stackoverflow.com/markdown and https://stackoverflow.com/help/formatting

To create "key-cap" formatting like Ctrl + Z, I discovered that it is necessary to use the kbd HTML tag. In this process, I (re?)learned that there actually is a standard <kbd> HTML tag. I write a lot of code, but I don't do a lot of manual HTML page markup.

Anyway, marking up text like this is a very useful thing to be able to do on Stack Exchange sites, but especially Stack Overflow and Super User. However, when I read the /markdown page, the information provided is simply:

If you need to do something that Markdown can't handle, use HTML. Note that we only support a very strict subset of HTML!

To reboot your computer, press <kbd>ctrl</kbd>+<kbd>alt</kbd>+<kbd>del</kbd>.

This is not very informative. We only find out implicitly that the kbd tag is supported by the fact that it's in the example, or by following a link to a separate document (actually a meta.SE post). We aren't directly told that the HTML markup is the expected way to solve this specific problem; we need to have a) the insight that HTML supports such a tag and b) the guess that a technically-oriented site would provide decent CSS for it. We cannot search the page for keycap or anything like that (unless we think of kbd, in which case we have already defaulted to the "maybe we need to use HTML for this" answer).

I don't think it's at all obvious that "use HTML" is the expected way to solve this problem (as opposed to some kind of explicit support in the Markdown flavour used). Consequently, I think the help page should explicitly call out this use case and say to use HTML to solve the problem.

The /help/formatting page is even worse in this regard; it does not show any HTML examples at all, although it mentions "we support some HTML" at the top. This is especially galling since this is the version of the page that's explicitly in the Help section. (Actually, it's galling that there are two totally separate documentation pages for the same concept in the first place, written in completely different styles....)

8
  • 1
  • 2
    Finding/navigating to those (semi-redundant) Pages (you forgot the /editing-help one) is always a bit of a hassle, kind of "hidden" in the 'Help Center' in the 'Our Model' Section while those are the only Pages I ever need to check back from the 'Help', there should be some clear and easy to find 'Post Formatting' Section. // Info about supported HTML Tags in this SE-Meta Thread: "What HTML tags are allowed on Stack Exchange sites?"
    – chivracq
    Commented Sep 3, 2022 at 10:28
  • 4
    Yes, discoverability is a problem. To prevent abuse? :-) But this is amazing. Commented Sep 3, 2022 at 11:29
  • 1
    This really leads to the question of "where should the lines be drawn between information in the 'Formatting Help' page, 'Markdown help' page, and the supported HTML tags reference Q&A?" The <kbd></kbd> tag is very clearly HTML, not Markdown, so, at least from a semantic point of view, belongs on the HTML tags reference page. When does straight HTML become important enough to be explicitly on the 'Markdown help' page or 'Formatting Help' page? Are there really enough posts in which <kbd> tags would be appropriately used to justify having them explicitly detailed on either of those pages?
    – Makyen Mod
    Commented Sep 3, 2022 at 17:37
  • I think "Markdown" is largely treated as synecdoche for the entire set of things you can do to format the post. At least, it's hard to understand why it would be valuable to have the information about Markdown and non-Markdown ways to format the post in separate places. Commented Sep 3, 2022 at 21:17
  • NB: Other useful HTML tags and HTML character entity references are &rarr;, &nbsp;, <sub></sub>, <sup></sup>, &middot;, &ndash;, and &mdash; (though there are Unicode alternatives for some of them). Commented Sep 3, 2022 at 21:26
  • 1
    I don't think Markdown is a synecdoche here. The reason to document Markdown in the Help Center is because it is (was, at least at the time that SO was launched) something unique to this site, whereas HTML tags are not in any way unique and already documented multiple places.
    – Cody Gray Mod
    Commented Sep 4, 2022 at 11:42
  • This uber-meta dupe covers this case just fine: "What HTML tags are allowed on Stack Exchange sites?". "Markdown" is irrelevant here, we're not talking about MD syntax.
    – Cerbrus
    Commented Sep 5, 2022 at 15:19

0

You must log in to answer this question.

Browse other questions tagged .