-
Notifications
You must be signed in to change notification settings - Fork 22.4k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
format fix for HTML button doc #4792
Conversation
relocate a </strong> tag in the intro to be consistent with more common MDN styling
Preview URLsFlawsURL:
External URLsURL: No new external URLs |
I like your format better, but the other form seems much more prevalent in the HTML docs. From a random sample of 12 pages they seem to follow two main forms:
or:
I think with the first form it makes sense to have the whole thing in bold. But I like the second form better: it's more concise and direct, and I think with HTML elements people think in terms of the tag name - noone says "I used a Content Division element". And I agree with the second form it is more natural to make only the tagname strong (maybe not even "HTML" either, we don't do that with e.g. CSS (https://developer.mozilla.org/en-US/docs/Web/CSS/grid)). So we could just choose to go with:
...throughout the docs. I'm interested to hear what other people think. @ddbeck , @Elchi3 , @hamishwillee ? |
It's not so much my format or what I think the format should be. It is my subjective perception of the prevailing format in MDN docs for CSS, JS, and HTML. FWIW, I have recently spent more time in the JS docs than the others. To offer an opinion: to my eye, the use of bold (and italic) type can be a little enthusiastic on MDN. Generally, I would suggest that emphasis works best when it is applied sparingly. In this particular usage, does the meaning or priority of the communication change significantly with the emphasis reduced? |
@wbamberg I agree with this. As far as I can tell, the HTML spec doesn't ever use words "content division" or "unordered list" and I can't figure where they came from. Seems kinda weird that we provide these alternate names for elements. The bold text stuff I'm indifferent to—at least, I wouldn't be inclined to go around fixing that alone—though @timohaver is probably right that we overdo it a little. Reducing it to the tag itself (or eliminating it outright) would be fine. |
@wbamberg, @timohaver Not sure what this PR is waiting on |
This sparked a discussion in https://github.com/mdn/content/discussions/5131 which looks like it might have actually been resolved now. So we should either update this PR to use a form like:
...or close it and file a separate issue to update all the HTML element docs. |
In fact let's close this in favour of #5352. But thanks @timohaver for starting this conversation! |
relocate a tag in the intro to be consistent with more common MDN styling
MDN URL
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button