Can Not Find MDN Style Guide

MDN
#1

I want to learn to interpret MDN documentation better but I can not find a style guide pertaining to the documentation itself (as in internal mozilla document that tells you the meaning of symbols and other things about how THEIR documentation is written).

For Example: The little flask looking icon found next to some items here: https://developer.mozilla.org/en-US/docs/Web/CSS/Pseudo-classes#alphabetical_index

But I’m not JUST looking for an answer to the example above but a complete guide to all notation and symbols used in mozilla documentation.

Thanks

#2

Hi @blahboybaz and welcome to the community :wave:

When you go on a page with such a symbol, there’s a note at the top describing it. The three symbols that come to my mind are:

  • flask: experimental

    This is an experimental technology
    Check the Browser compatibility table carefully before using this in production.

  • trash can: deprecated

    This feature is no longer recommended. Though some browsers might still support it, it may have already been removed from the relevant web standards, may be in the process of being dropped, or may only be kept for compatibility purposes. Avoid using it, and update existing code if possible; see the compatibility table at the bottom of this page to guide your decision. Be aware that this feature may cease to work at any time.

  • triangle with exclamation mark

    This feature is non-standard and is not on a standards track. Do not use it on production sites facing the Web: it will not work for every user. There may also be large incompatibilities between implementations and the behavior may change in the future.

In some situations (like the browser compatibility tables) you can hover over the symbol to see a short description.

I hope that helps!

Cheers,
Michael

#3

Thanks @mikoMK but I don’t see what you are talking about on that page: https://developer.mozilla.org/en-US/docs/Web/CSS/Pseudo-classes#alphabetical_index

Symbol Seen at section: https://developer.mozilla.org/en-US/docs/Web/CSS/Pseudo-classes#alphabetical_index

I don’t see any references to symbols at the top of the page or at the top of the alphabetical index section at the end. Hovering over the symbol does nothing. I don’t see a link to anything like that in the right or left columns. Besides, if it exists, I would like to have a go-to document that addresses the topic of MDN docs comprehensively rather than just learn this thing or that thing as it arises.

Thanks

1 Like
#4

Sorry, that my answer wasn’t clear enough :roll_eyes:

What I mean was: If you, for example, click on :blank on your linked page (which has the flask icon), you see the note I was talking about at the start of the article.

I also found https://developer.mozilla.org/en-US/docs/MDN/Guidelines/Conventions_definitions which describes the “experimental” and “deprecated” status among other things but isn’t prominently linked somewhere.

Maybe it would be a good idea to open an issue on the MDN GitHub repo:

Have a nice day,
Michael

PS: Your email address is visible in your post. I think it somehow ended up in the optional “name” field of your profile. I recommend removing it.

1 Like
#5

Thanks @mikoMK. I see what you mean now. Thanks for the link too. I’ll check that out. I’ve never seen such a large and robust body of information not have a readily available style guide that defines how they convey their content. At any rate - your help is much appreciated.

1 Like
#6

For the record I just found my email address displayed via this thread. It turns out it was in the “Name” field in my profile and I was unaware of it. I don’t believe I had anything to do with it ending up there (not that I recall). I have corrected the situation but you guys may want to check whether this is being done by default when a new account is created.

https://discourse.mozilla.org/t/can-not-find-mdn-style-guide/

#7

Thanks for the info. That’s what I mentioned at the end of my last post.
At the moment when creating a new account, the form auto-fills the optional “name” field with the email address. We informed the admins about the situation some time ago, but it isn’t fixed, yet.

Cheers,
Michael