While docs on the MDN Web Docs site are mainly about code, some of them refer to user interface elements in browsers or other tools that developers use. We don’t have any style guidelines about how to refer to and format UI elements, so we have a fair amount of inconsistency across such docs.
I propose that we follow the Google Developer Documentation Style Guide’s section on UI elements and interaction. Reasons to use it are that it’s available online under an open license, and it’s meant for documents with a similar audience to MDN’s. Of the current style guides I’ve looked at, it aligns the best with MDN’s content domain and audience.
The only exception I would make to the GDDSG is that it recommends using <b> for UI item names, rather than <strong>, to indicate visual emphasis rather than importance of the content. While this recommendation is semantically correct, MDN’s visual editor supports only <strong> from the toolbar. Modifying the editor toolbar to support both tags would probably create confusion for some contributors; requiring contributors to go into source mode to mark up UI elements would be onerous. Therefore, I suggest we take the practical, if impure, route of ignoring that recommendation.
If this proposal is acceptable, I can add a link from the MDN Writing style guide article to that section of GDDSG.
I could cope with this. The only worry I’d have is that bold/strong is often used to refer to new terms or important terms (I tend to use italics for UI items). Do we think this would be a problem in any way?
I am happy to go with a consensus here, and I’m glad you’re thinking about this.
I have a number of problems with the Google style guide for UI elements. It recommends word usage that differs from the rest of MDN, such as recommending the word “pane” instead of “panel”, “command” instead of “option” or “menu item”, and so on.
It also recommends using boldface far too much, IMO. For instance, it says to boldface UI element names, such as window names, menu and menu item names, etc. This is confusing since we already use boldface in other ways. We should instead create a style that we can use similarly to the one that we apply to <kbd> to make those stand out properly while being distinct from other bold uses.
There is good stuff in there, but I definitely have concerns and think we need to have our own guidelines here instead to incorporate our variations, instead of simply pointing to Google’s.
I was hoping not to have to reinvent, and then maintain, this wheel, for something that’s used on relatively few MDN pages. Is there another guide out there that’s closer to current MDN usage?
Since we already have so much to maintain, this small amount of added style guide content hardly seems like it’s a huge added burden at this point. It would be different if we were considering adopting externally produced site-wide style guidelines, which isn’t on the table here.
We can certainly base our guidelines on existing ones, to save time. I’m just not sure that having guidelines with significant deviations from our current practices makes sense.
That’s just my opinion, of course. I’m big on content consistency; I think it’s pretty important to making your material feel like it’s of high quality, and it makes things easier to maintain in the long run.
I guess it’s a matter of what style you’re used to.