3 ms·

I wish they'd update their docs with better examples before creating content in other areas, such as tutorials and blogs. As an example, when comparing these t

by itsuka 3y ago

I wish they'd update their docs with better examples before creating content in other areas, such as tutorials and blogs. As an example, when comparing these two pages: - Blog: https://developer.mozilla.org/en-US/blog/css-color-module-level-4 https://developer.mozilla.org/en-US/blog/css-color-module-le... - Reference: https://developer.mozilla.org/en-US/docs/Web/CSS/color https://developer.mozilla.org/en-US/docs/Web/CSS/color It is apparent that the reference page lacks any mention of features from level 4 such as oklch, display-p3, and color function. Also, a search for "display-p3" in the search bar returns no result on that page.

chrismorgan 3y ago
You’re looking at the reference page for the ‘color’ property, but that’s the wrong thing: all this stuff belongs on the page for the <color> data type; and that’s where it’s found: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value https://developer.mozilla.org/en-US/docs/Web/CSS/color_value. Frankly, I’d prefer the color property page (and background-color, and border-color, and …) to deliberately not have so many diverse examples, and link much more prominently to the <color> page.
- itsuka 3y ago
  You're right. I am not as familiar with MDN's organization and CSS as you are (I only recently discovered that CSS is a typed language). However, I find it confusing that some pages have their own page for values, while others don't. As a reference page, I expect the valid syntax for all values to be provided. But I agree that specific examples can be linked to other resources.
  - chrismorgan 3y ago
    Things like colours and units get used in many properties (color, background-color, border-color, box-shadow—in which <color> is only a part of the syntax—and many more; width, length, font-size, font—a shorthand in which <length> is only a part—and many more), and if they get expanded in one place, then all properties that use them take the new definition—hence <color>, <length>, &c. as the only sensible way to structure things (in spec, reference and mental model). By contrast, the values of properties like ‘display’ aren’t used anywhere else. It sounds like a large part of the problem is helping to build the right mental model. If you understand that colours and lengths are used in many places, it will make sense that they will be documented separately from the properties, and that the properties’ references will just refer to them.
    - itsuka 3y ago
      Thank you for taking the time to explain things so clearly to me. Considering the reuse, having values in a separate page makes sense now.

by itsuka 3y ago

chrismorgan 3y ago

You’re looking at the reference page for the ‘color’ property, but that’s the wrong thing: all this stuff belongs on the page for the <color> data type; and that’s where it’s found: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value https://developer.mozilla.org/en-US/docs/Web/CSS/color_value. Frankly, I’d prefer the color property page (and background-color, and border-color, and …) to deliberately not have so many diverse examples, and link much more prominently to the <color> page.

itsuka 3y ago
You're right. I am not as familiar with MDN's organization and CSS as you are (I only recently discovered that CSS is a typed language). However, I find it confusing that some pages have their own page for values, while others don't. As a reference page, I expect the valid syntax for all values to be provided. But I agree that specific examples can be linked to other resources.
- chrismorgan 3y ago
  Things like colours and units get used in many properties (color, background-color, border-color, box-shadow—in which <color> is only a part of the syntax—and many more; width, length, font-size, font—a shorthand in which <length> is only a part—and many more), and if they get expanded in one place, then all properties that use them take the new definition—hence <color>, <length>, &c. as the only sensible way to structure things (in spec, reference and mental model). By contrast, the values of properties like ‘display’ aren’t used anywhere else. It sounds like a large part of the problem is helping to build the right mental model. If you understand that colours and lengths are used in many places, it will make sense that they will be documented separately from the properties, and that the properties’ references will just refer to them.
  - itsuka 3y ago
    Thank you for taking the time to explain things so clearly to me. Considering the reuse, having values in a separate page makes sense now.