CSS module landing page

[estelle]

Part of Q1-2023 project openwebdocs/project#147

Note, w3c/browser-specs#851 should fix the spec name appearing the same for 2 different specs on the blending and compositing page.

[github-actions]

Preview URLs

• /en-US/docs/Web/CSS/CSS_Animations
• /en-US/docs/Web/CSS/Compositing_and_Blending

Flaws (1)

Note! 1 document with no flaws that don't need to be listed. 🎉

URL: /en-US/docs/Web/CSS/CSS_Animations
Title: CSS animations
Flaw count: 1

• macros:
  • /en-US/docs/Glossary/B%C3%A9zier_curve redirects to /en-US/docs/Glossary/Bezier_curve

External URLs (3)

URL: /en-US/docs/Web/CSS/Compositing_and_Blending
Title: CSS compositing and blending

• https://code.tutsplus.com/tutorials/editing-images-in-css-blend-modes--cms-26058 (1 time) (Note! This may be a new URL 👀)
• https://web.dev/learn/css/blend-modes/ (1 time) (Note! This may be a new URL 👀)
• https://www.sarasoueidan.com/blog/compositing-and-blending-in-css/ (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2023-02-01 16:28:18)

[wbamberg]

Overall I think this looks great.

I created a test module landing page so we could discuss the CSS module landing page format for the Q1 project openwebdocs/project#147

What do you all think of the format of this CSS module landing page?

Do the headings make sense for the CSS module landing template?

Idea:

• 3 to 5 paragraphs about the module

• Example (should this be in line, or have its own h2 level heading?)

• Things to note, if any, about the module, displayed in the example. This being inline, not its own heading.

• Reference

  • Properties
  • Data Types

We don't usually capitalize "Types" here: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Types .

• Functions, or other important to module reference, if any (not present in this example)
• Guides (not in this page, but if they were, is this the right spot?)

I think if we have guides they should be under their own H2. Guides aren't reference.

• Associated content (not present in all modules, but likely in most)

  • associated properties
  • associated datatypes from other modules
  • associated concepts (things you need to know to get this module to work, such as time or hardware acceleration in animations)

• Specifications (note, Make compositing-2 current, fix series.releaseUrl logic w3c/browser-specs#851 should fix the spec name appearing the same for 2 different specs)

• See also - this would generally be for internal learn and guides, but we don't have anything on blending, so these are external.

Why wouldn't would "internal learn and guides" be in Guides?

[wbamberg]

Should this be H2? And why not show source for the example? And might we want to have more than one, and then call it Examples?

I would have the example after the Reference and Associated content, as we usually do for docs (interactive examples aside).

[estelle]

I actually didn't want to have a header at all, but didn't know how to show EmbedLiveSample without a header ID. I want to keep the code hidden as this is supposed to be a very brief overview of "why" you would want to dig into the module, not an explanation of what the properties are or how they work. The example is part of the description, not an explanation, which is why it is with the description of the module.

The example also uses a lot of properties and values that are irrelevant to the module, such as borders, grid, backgrounds, gradients. Hiding the code enables including a complex example that shows the power of the whole module without worrying that the reader will get stuck on the details.

[estelle]

Why wouldn't would "internal learn and guides" be in Guides?

I meant related articles that aren't mainly about the module, such as improving performance for scrolling, animation, and transitions. Yes, it discusses some features in the module, but it's not about the module.

[dipikabh]

Hi @estelle, I am a bit uncomfortable with duplicating content across pages. Because it increases our burden of keeping the same content up-to-date in all the pages that it appears.

There are two places where a concept/topic/module has a place in the sidebar - "Reference > Modules" and "Guides".

1. How about we keep the page under "Reference > Modules" as purely a landing page, with links to all the related pages, and move all overarching explanations and examples to the Guides pages?
2. How about we come up with a template for the landing page before touching all the module pages? We will eventually need one to ensure consistency across such pages.

• 3 to 5 paragraphs about the module
• Example (should this be in line, or have its own h2 level heading?)
• Things to note, if any, about the module, displayed in the example. This being inline, not its own heading.

All this to me seems to be duplicating content and examples that one might find in the specific property page or in the respective guide. To look at it in another way, is this content/example that will not be covered in a guide or a property page?

• Associated content (not present in all modules, but likely in most)
  • associated properties
  • associated datatypes from other modules
  • associated concepts (things you need to know to get this module to work, such as time or hardware acceleration in animations)
  • glossary terms (is this the right spot?)

How about this instead (dropped the repetitive 'associated'. I've used 'related' because it sounds easier and lighter to read and say):

• Other related content
  • Properties
  • Data types
  • ...

Can "Glossary" terms be combined with "See also"?

Looking at a few existing pages:

• The content on these pages look like they belong in a guide: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Box_Alignment and https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Columns
• These seem to have a decent enough structure for a landing page: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Animations and https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Images. We'll need to define in the template if we want to include a description for guides and also whether "See also" entries will be just links or descriptions :)

[dipikabh]

Hi @estelle, the structure of the page looks good as well as the scoping of information. I've added some edits and questions.

[dipikabh]

should/can there be an order to list these? alphabetical within a category

[estelle]

I set them in order of relevance. Filter, which does something similar, seemed more relevant than background properties, which I then did put in alphabetical order.

[dipikabh]

LGTM, @estelle. Thank you for the updates!

[dipikabh]

Lol, that comment was supposed to be 'blank line' not 'black line'