Rationale behind "no code in headings"?

[SphinxKnight]

Hello there,

Is there any objective rationale behind the practice consisting not to put any code syntax in headings?

What is now https://github.com/mdn/content/blob/167f9ca3eb17f4039f885434304bcc01aab5152d/files/en-us/mdn/writing_guidelines/writing_style_guide/index.md?plain=1#L436-L438 was before https://github.com/mdn/content/blame/38c720f0a23b7b2f02a062876d99fd543d200ad0/files/en-us/mdn/guidelines/writing_style_guide/index.md#L146

As a reader, it makes more sense to me to see the keyword as code, even in a heading.
Moreover, when localizing it's also clearer for non-native English readers to identify such a word/words:

So if I'm missing something obvious, please let me know :)

[jpmedley]

There are a few, actually. First you have to look at the reason why code is in text. In computer science contexts, it needs to be clear whether a piece of punctuation is part of the code item or part of the sentence. This isn't really an issue in titles, which tend to be short and light on punctuation. The next question to ask is what value does it bring to a title? Formatted code references have the advantage of helping your eyes find them on the page. But titles already have that advantage since they are typically set off by some combination of extra space, bolding, and increased size. At this point special formatting adds something that headings no longer need. They can also start to detract from the overall appearance of the page. In the worst case, they can lead to a page being unscanable. Scanability depends on some things being different. A page with too much of a formatting mix can be hard to scan for anything.

[nschonni]

Again, all anecdotal, but other large documentation repos like the Microsoft or GitHub docs use code fences in titles often for the same elements that would use code spans in the text blocks. I agree totally with striping out emphasis and strong tags from headings, but it is an i18n issue when you don't have a way of differentiating keywords in headings

[SphinxKnight]

From a non-native English speaker perspective, I'd say it helps "scanning" the page more than the contrary. I didn't look for statistics on the pages of MDN but I'd say this does not constitute the majority of headings / pages and this problem (unscanability) should be rare.

Moreover, even if we're using Markdown and not HTML for reasons, semantics are still relevant and this does not seem to be a high cost to enrich the content with backticks to indicate a code word.

[Josh-Cena]

I strongly prefer using code in titles—even for English content, this avoids ambiguity. For example, when you see ### Using this, does that mean "Using this API"? "Using this code example"? "Using this"? Apparently in MDN conventions we mean the last, but users may get confused. Similarly, "Using with with a proxy", what we actually mean is "Using with with a proxy", but in the end we have to rewrite it as "Using the with statement with a proxy", which is unnecessarily long.

However, the ship has sailed—I've already removed a lot of code in headings, so it might be too late for any changes after all.

[nschonni]

I don't think it's too late, the current guidance can just be removed and they'll naturally come back as people edit things.

[SphinxKnight]

I opened mdn/content#22472 to go a step further.

[Rumyra]

Hey folks! Sorry we didn't reply to this a bit earlier - I think when peeps don't have strong opinions about things discussions tend to hang around a bit.

After a quick chat about it I'm going to merge @SphinxKnight 's PR and say yes it's ok to have code in headings. The reason for not was to keep the headings plain text, but considering at this time we have no real technical reason for that, and the points above are valid we'll have code in headings 👍

[bsmth]

Closing as answered in https://github.com/orgs/mdn/discussions/271#discussioncomment-4225841

Thank you, all!