Have a consistent opening paragraph for HTML elements

[wbamberg]

This came out of mdn/content#4792 , which changes the preamble bit for https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button from:

"The HTML <button> element represents..."

to

"The HTML <button> element represents..."

It would be nice to be consistent here, and it would be good to know what people think we should use. Some options:

1. "The HTML Content Division element (<div>) ..."
2. "The HTML <div> element ..."
3. "The HTML <div> element ..."
4. "The HTML <div> element ..."
5. "The <div> element ..."

Having written all these out, I think I like 4 best. I believe the extra words in (1) was connected with SEO, but I'm not sure that's really a good reason to do it.

• the JS docs use "The slice() method ... ", which is more like (5)
• the CSS pages uses "The box-shadow CSS property ..." which is close to (4), but also links to the main CSS page. We could do the same for (4) above.
• the Web API pages seem to do "The error() method of the Response interface ...", which is somewhere in the (4)/(5) territory.

[hamishwillee]

Of the options presented I prefer option 4. In particular IMO only the element itself should be highlighted in bold (and I even consider that "optional").

If the HTML context is important (and I think it is), then arguably this is a better approach:

In case it is helpful

[wbamberg]

If we can agree, I'm going to open a PR to update the HTML element preamble bits along the lines of option 4 above. Hamish and I both agree this is the best option (of the ones listed), and I believe @ddbeck is fairly well-disposed as well, given mdn/content#4792 (comment).

It would be nice to be consistent here.

Any other/dissenting views? @Rumyra , @Elchi3 ?

[ddbeck]

I would never have thought about it except seeing "The box-shadow CSS property ..." made me think that "The CSS box-shadow property" sounds wrong, therefore the HTML version might also be wrong? Or maybe some subtly different grammatical rule applies here. 🤷

[hamishwillee]

@wbamberg FWIW and FYI only I prefer HTML in the title (even over option 4) as shown below. Essentially the fact that it is an HTML element is important, so the title feels like the right place. And if it is there, the type doesn't need to be said in the text.

That's just a preference and I will happily go with the consensus. I'm also happy with same format for CSS - does not feel wrong to me.

"The CSS box-shadow property

[ddbeck]

OK, if it's not wrong to have either one first, then can we pick one and do the same for both? If we're already changing HTML it kinda makes sense for it to align to CSS, so we don't have to change both. But I would also accept a coin toss a selection method.

[wbamberg]

I would never have thought about it except seeing "The box-shadow CSS property ..." made me think that "The CSS box-shadow property" sounds wrong, therefore the HTML version might also be wrong? Or maybe some subtly different grammatical rule applies here. 🤷

Having thought about it, I feel the same, "The CSS box-shadow property" sounds wrong to me too, so it must just be what we are used to. If none of us can think of a reason for one over the other, let's change the HTML, because it's less consistent already and it's much smaller. So:

The <div> HTML element

it would be.

@wbamberg FWIW and FYI only I prefer HTML in the title (even over option 4) as shown below. Essentially the fact that it is an HTML element is important, so the title feels like the right place. And if it is there, the type doesn't need to be said in the text.

Yes, I can see the logic of including that in the title. But then again we get into consistency: we don't include the name of the technology in the title for CSS, JS, or Web APIs, or anything else. Should we? Should we block this change on agreeing that and updating all 8000-odd pages? I think I'd prefer for us to limit the scope of this, for now.

[hamishwillee]

Re ^^^ I feel title update would "probably" be better for CSS and HTML even if we didn't include anything in the others (i.e. I don't feel the need for consistency except within the document type). I wouldn't do it at the cost of updating every doc. I don't feel strongly enough to fight this point of view (to me this is a "detail" discussion - there are much bigger flaws in MDN to address - I'd rather invest in helping get markdown right! )

Completely happy that being consistent on the following would be better than the current situation, and represent "broad consensus":

The <div> HTML element

The box-shadow CSS property

[wbamberg]

OK, thanks for all the discussion. I'm filing mdn/content#5352 to track the work, based on a pattern like:

The <div> HTML element

[wbamberg]

This is done -> mdn/content#5580 - thanks @rachelandrew !