Sprints: Learn CSS Rewrite 2.2 Selectors

[rachelandrew]

Individual tasks for the rewrite of the learning CSS section. This one for the second part of the CSS Building Blocks section.

Broken down into pages for the various types of selectors as in the current guide.

https://docs.google.com/document/d/1vN0gWLZe_IweWJnYi9q1eMBUsaxdafxfu-ed383nPI8/edit?usp=sharing

[rachelandrew]

This is what I mentioned in our call. Not ready for review yet but I wanted to see what you think.

I have a main overview which details some common things about selectors:

https://developer.mozilla.org/en-US/docs/user:chrisdavidmills/CSS_Learn/CSS_Selectors

Then, as well as working through the subpages detailing the different selectors individually, I am creating a table at the bottom as a kind of quick reference to the selectors you have.

The first subpage is here (again, still a rough draft): https://developer.mozilla.org/en-US/docs/user:chrisdavidmills/CSS_Learn/CSS_Selectors/Type_Class_and_ID_Selectors

I think there is a benefit in being reasonably thorough with these and also giving a nice neat reference overview that isn't bogged down by the more technical stuff in the main docs.

Anyway, let me know what you think before I continue down this path.

[chrisdavidmills]

I like this approach. I think it is a good idea dealing with all the general stuff that applied to all major types of selector, and then going on to deal with the different types in followon tutorials. Go for it.

[rachelandrew]

So ... I think these are ready for review.

I linked them all up from here: https://developer.mozilla.org/en-US/docs/User:chrisdavidmills/CSS_Learn (CSS Selectors and the 4 subpages).

Just so you know, I've been copying in the previous and next code just so they have it, but it's all incorrectly linked as I'll only have to redo it once they are in their real location. I think I'll add a card for tasks which will need to be done when we make this all live.

[chrisdavidmills]

OK, so I've looked at the main selectors page, and I think it reads really well. I had a couple of comments:

1. In the section about selector lists, maybe add a note/reminder somewhere about whitespace not mattering inside selector lists, and a common style being to put each one on a separate line, something like

.class,
    h1 {
  ...
}

1. The end of the article is useful, but doesn't feel like a great learning experience for beginners. The table is a useful reference after they've met the selectors alreqdy, but on first meeting this, they'd probably be a bit scared and think "Eh? What do I do here?"

To fix this, I think it'd make sense to add a section before it along the lines of "what's next", in which you explain what different types of selectors the reader will meet, what they do, and what the learning journey looks like, e.g. "next, you'll move on to a more in-depth look at the simplest types of selectors — type, class, and ID selectors" (provide link)

[chrisdavidmills]

Comments on https://developer.mozilla.org/en-US/docs/User:chrisdavidmills/CSS_Learn/CSS_Selectors/Type_Class_and_ID_Selectors

"This means that instead of the default styling added by the browser, which spaces out headings and paragraphs with margins, everything is close together and we can't see the different paragraphs easily."

-- This makes the universal selector sound pretty useless to start off with. Maybe mention that below we'll look at some useful applications of it, and also perhaps mention CSS resets as being a thing that involve removing all margins, etc., why they used to be used a lot, and why we don't use them as much any more.?

"One use of the universal selector is to make selectors easier to read and more obvious in terms of what they are doing."

-- I've added a bit of explanation about the difference between the two confusing selector forms. However, I think you should consider adding something to say that :first-child is a pseudo class, what that is, and then link to the article section that covers pseudo classes later on.

You could may even consider adding a live example that allows the readers to play with this for themselves, e.g.

<body>
  <article>
    <p>First</p>

    <p>Second</p>   
  </article>

  <article>
     <p>Third</p>

    <p>Fourth</p>    
  </article>
</body>

article :first-child {
  color: red;
}

"Targetting classes on particular elements"

-- in this section, maybe say somewhere that this is not a particularly good idea (makes classes unnecessarily specific, harder to override, etc.), and that you should only do it if you really have to.

"as we learned in the lesson on specificity"

-- we'll have to remember to link this to the specificity article once they are put in their final places.

[chrisdavidmills]

Comments on https://developer.mozilla.org/en-US/docs/User:chrisdavidmills/CSS_Learn/CSS_Selectors/Attribute_selectors

"Can include multiple values in the form of a whitespace-separated list of words."

-- I've always found the [attr~=value] syntax confusing - when you include a whitespace-separated list of words, e.g. li[class~="a b"], what does this select? I can't seem to make it select anything useful. Can you add an example?

In the example that follows, you say "li[class~="a"] will match a class of a but also a value that contains the class of a as part of a list." This seems like more sensible usage, but it is different to what you are describing in the above table.

" in our case this is HTML, therefore matching will be related to the case-sensitivity of that attribute."

-- this is a bit confusing. Are you saying that it will behave differently inside for example, SVG, XML, etc.? I think this might be a bit confusing for beginners, so perhaps just say that by default matching is done case sensitively, but the i flag turns this off.

This also leads me on to think about the s flag — if the above is true, then isn't the s flag pretty much pointless? Should we just not bother to mention it?

-- There isn't much in the way of examples or exercises here. Could you add an example that asks the read the implement something, to test their skills?

[chrisdavidmills]

Comments on https://developer.mozilla.org/en-US/docs/User:chrisdavidmills/CSS_Learn/CSS_Selectors/Pseuso-classes_and_Pseudo-elements

-- I think having the giant tables of pseudo-classes and elements in the middle of the document could be a bit offputting to beginners. Maybe put them at the end of the article instead, in some kind of clearly labelled reference section? It is definitely useful to have available.

-- I would expect a bit more in terms of exercises and studies on how pseudo classes are used on the web, e.g. it would be nice to see sections on custom styling for link states, typographic styling such as indent of first paragraphs, styling of valid and invalid form elements, zebra striping, etc. We might include these somewhere later on, so maybe include links to further examples?

"Inserting strings of text isn't really something we do very often on the web however."

-- This seems like a strange statement; I mean, we do it all the time using JavaScript ;-) Seriously though, we quite often use generated content to insert things like icons that act as visual indicators of things form validity, notes or warnings, which we don't want to pollute the markup and be read out by screenreaders. Maybe even text used for decorative purposes. Maybe cut this line out, and change your current example to something a bit more real world, like including an icon?

[chrisdavidmills]

Comments on https://developer.mozilla.org/en-US/docs/User:chrisdavidmills/CSS_Learn/CSS_Selectors/Combinators

I have added a few bits of extra explanation in. I think it would be nice to you talked a bit more about the fact that these combinators can be combined with pretty much any other type of selector, not just simple ones, so readers don't get that idea.

In the Adjacent sibling example, I think it'd look better if you did something else to the first paragraph too, like turn it a dark grey, otherwise it just looks like you've got two headings right next to one another, one of which is actually a

. Maybe do this for the general sibling section too?

[rachelandrew]

Comments on https://developer.mozilla.org/en-US/docs/User:chrisdavidmills/CSS_Learn/CSS_Selectors/Type_Class_and_ID_Selectors

"This means that instead of the default styling added by the browser, which spaces out headings and paragraphs with margins, everything is close together and we can't see the different paragraphs easily."

-- This makes the universal selector sound pretty useless to start off with. Maybe mention that below we'll look at some useful applications of it, and also perhaps mention CSS resets as being a thing that involve removing all margins, etc., why they used to be used a lot, and why we don't use them as much any more.?

done

"One use of the universal selector is to make selectors easier to read and more obvious in terms of what they are doing."

-- I've added a bit of explanation about the difference between the two confusing selector forms. However, I think you should consider adding something to say that :first-child is a pseudo class, what that is, and then link to the article section that covers pseudo classes later on.

You could may even consider adding a live example that allows the readers to play with this for themselves, e.g.

that doesn't make sense here as we haven't talked about pseudo-classes yet. I'm not sure what purpose it would serve either.

"Targetting classes on particular elements"

-- in this section, maybe say somewhere that this is not a particularly good idea (makes classes unnecessarily specific, harder to override, etc.), and that you should only do it if you really have to.

done

"as we learned in the lesson on specificity"

-- we'll have to remember to link this to the specificity article once they are put in their final places.

yes I think I need to make a list as I mentioned somewhere else.

[rachelandrew]

Comments on https://developer.mozilla.org/en-US/docs/User:chrisdavidmills/CSS_Learn/CSS_Selectors/Pseuso-classes_and_Pseudo-elements

-- I think having the giant tables of pseudo-classes and elements in the middle of the document could be a bit offputting to beginners. Maybe put them at the end of the article instead, in some kind of clearly labelled reference section? It is definitely useful to have available.

done - we don't really have anything that just explains what there is and what it does so I thought it might be helpful.

-- I would expect a bit more in terms of exercises and studies on how pseudo classes are used on the web, e.g. it would be nice to see sections on custom styling for link states, typographic styling such as indent of first paragraphs, styling of valid and invalid form elements, zebra striping, etc. We might include these somewhere later on, so maybe include links to further examples?

I could go on and on with this but I'm not convinced it is necessary (in fact one of the things you initially asked was to cut this all down) I wanted to show the different types of pseuso-class / element and give an example of things that might confuse, for example the dynamic ones, and generated content. However the other things idealy they would see in use through the rest of the articles, and they all pretty much follow the same pattern.

If anything those sort of things would make good cookbook examples rather than stuffing loads of them in here IMO.

"Inserting strings of text isn't really something we do very often on the web however."

-- This seems like a strange statement;

I've clarified but I stand by it, there are very few genuine reasons to stick text into strings in your CSS, most times I see it in production when doing audits I'm advising to stop doing it. "On the web" is because if you are talking CSS for print, sticking text in with generated content is about 50% of the job, but we don't need to go there!

[rachelandrew]

Comments on https://developer.mozilla.org/en-US/docs/User:chrisdavidmills/CSS_Learn/CSS_Selectors/Attribute_selectors

"Can include multiple values in the form of a whitespace-separated list of words."

-- I've always found the [attr~=value] syntax confusing - when you include a whitespace-separated list of words, e.g. li[class~="a b"], what does this select? I can't seem to make it select anything useful. Can you add an example?

the whitespace list is the value of the class attribute, as in the example below. So, there is an example?

In the example that follows, you say "li[class~="a"] will match a class of a but also a value that contains the class of a as part of a list." This seems like more sensible usage, but it is different to what you are describing in the above table.

yes that's the example - I'm quite confused now! :D

" in our case this is HTML, therefore matching will be related to the case-sensitivity of that attribute."

-- this is a bit confusing. Are you saying that it will behave differently inside for example, SVG, XML, etc.? I think this might be a bit confusing for beginners, so perhaps just say that by default matching is done case sensitively, but the i flag turns this off.

yes that's right, if the document type is something else ...which is why the s flag exists. But no we don't need to mention it if you don't want to.

[rachelandrew]

"OK, so I've looked at the main selectors page, and I think it reads really well. I had a couple of comments:

In the section about selector lists, maybe add a note/reminder somewhere about whitespace not mattering inside selector lists, and a common style being to put each one on a separate line, something like"

I had already mentioned whitespace (maybe you meant the line break?), but have added an additional example showing the formatting with a line break.

"To fix this, I think it'd make sense to add a section before it along the lines of "what's next", in which you explain what different types of selectors the reader will meet, what they do, and what the learning journey looks like, e.g. "next, you'll move on to a more in-depth look at the simplest types of selectors — type, class, and ID selectors" (provide link)"

have a look now.

[chrisdavidmills]

Further comments on https://developer.mozilla.org/en-US/docs/User:chrisdavidmills/CSS_Learn/CSS_Selectors/Type_Class_and_ID_Selectors

that doesn't make sense here as we haven't talked about pseudo-classes yet. I'm not sure what purpose it would serve either.

That's OK — I see you've added more explanation and a place to link to the pseudo-classes article that we can add when they are online. I also added a link to the :first-child reference page. I think this is fine.

[chrisdavidmills]

More comments on https://developer.mozilla.org/en-US/docs/User:chrisdavidmills/CSS_Learn/CSS_Selectors/Pseuso-classes_and_Pseudo-elements

I could go on and on with this but I'm not convinced it is necessary (in fact one of the things you initially asked was to cut this all down) I wanted to show the different types of pseuso-class / element and give an example of things that might confuse, for example the dynamic ones, and generated content. However the other things idealy they would see in use through the rest of the articles, and they all pretty much follow the same pattern.

If anything those sort of things would make good cookbook examples rather than stuffing loads of them in here IMO.

Yeah, I think you're right here. Some more cookbook examples would be nice in the future. For now, I think it would be great to just link to some good examples of pseudo classes in use so the curious can see some more examples.

I've clarified but I stand by it, there are very few genuine reasons to stick text into strings in your CSS, most times I see it in production when doing audits I'm advising to stop doing it. "On the web" is because if you are talking CSS for print, sticking text in with generated content is about 50% of the job, but we don't need to go there!

Fair enough, I agree with the logic here. But I still think the example should show something like an icon being added in, as a better real world example. Maybe show both the text example as it is more immediately playable, and then follow up with the icon example?

[chrisdavidmills]

Main selectors page — all looks good now. I've given it a few small edits, but happy with this!

[chrisdavidmills]

The attribute selectors article. I think I now understand this correctly, and have made a few changes in the description of the ~ version. Can you have another read of https://developer.mozilla.org/en-US/docs/User:chrisdavidmills/CSS_Learn/CSS_Selectors/Attribute_selectors#Presence_and_value_selectors and let meknow if you are happy with it?

If you are happy, I'm happy.

[rachelandrew]

In the Adjacent sibling example, I think it'd look better if you did something else to the first paragraph too, like turn it a dark grey, otherwise it just looks like you've got two headings right next to one another, one of which is actually a

. Maybe do this for the general sibling section too?

Just committed this change.

[rachelandrew]

Fair enough, I agree with the logic here. But I still think the example should show something like an icon being added in, as a better real world example. Maybe show both the text example as it is more immediately playable, and then follow up with the icon example?

extra example added.

[chrisdavidmills]

Just committed this change.

Great — this is much clearer now, thanks.

extra example added.

Cool, this is just the kind of thing I was after.

[rachelandrew]

I have just added an extra part to attribute selectors for people to try out the example. Which I think is the last thing you asked for.

https://developer.mozilla.org/en-US/docs/User:chrisdavidmills/CSS_Learn/CSS_Selectors/Attribute_selectors

Should we have a solutions page with the solution and a short explanation? I see on existing ones you have a "show solution" button but I feel as if, where someone was confused, they might just click that and not really understand why? My learning materials for my pilot's license, the tests all have a section at the end which explain why the thing is as it is, and that's quite useful.

Anyway I think I have done all the second draft bits.

[chrisdavidmills]

Should we have a solutions page with the solution and a short explanation? I see on existing ones you have a "show solution" button but I feel as if, where someone was confused, they might just click that and not really understand why? My learning materials for my pilot's license, the tests all have a section at the end which explain why the thing is as it is, and that's quite useful.

The new section looks good. In terms of solutions pages, I quite like this idea, yes. How do you want to do this? A separate page on MDN, or a page hidden on the GitHub repo that contains the code and explanation? I personally think the latter would be easier to manage, but I'm open to suggestions.

Anyway I think I have done all the second draft bits.

Looks like it. Nice work on these Rachel, thanks!

[rachelandrew]

The new section looks good. In terms of solutions pages, I quite like this idea, yes. How do you want to do this? A separate page on MDN, or a page hidden on the GitHub repo that contains the code and explanation? I personally think the latter would be easier to manage, but I'm open to suggestions.

A page on the GitHub repo sounds like a plan. I'll start that, we can always move it later if we change our minds.

[rachelandrew]

I think the last thing here was to start that solutions page, with the solution for: https://developer.mozilla.org/en-US/docs/User:chrisdavidmills/CSS_Learn/CSS_Selectors/Attribute_selectors

It is now here (and linked from that page): https://github.com/mdn/css-examples/blob/master/learn/solutions.md

I'll add any others that come up.

[chrisdavidmills]

I think this is all looking pretty good now. Read to go on MDN when the time comes!