Copy edit of 2020 CSS chapter

[tunetheweb]

Progress on #1432 and #898

Made the following changes:

• Set all graphs to use san-serif on labels for those that don't have Roboto installed
• Added labels to a few graphs
• Changed gradient-with-most-stops to be 1px high reducing it from 14 KB to 1.5 KB — if we're gonna call out the site for using 8 KB of CSS instead of doing this guess we should do it right 😁
• Removed smart quotes (see Use of typographic quotes or "smart quotes" in the Web Almanac #1485)
• Lowercase web as per our style guide
• Change "stylesheet" to "style sheet" as per our style guide
• Moved a few commas to em-dashes where sentence already included a lot of commas
• Removed a lot of italics and bold emphasis as felt not needed.
• Added some missing code formatting
• Added a load of TODOs with questions, queries and suggestions for authors. Will call these out below.
• Other standard edits
• Removed unedited tag

[github-actions]

Images automagically compressed by Calibre's image-actions ✨

Compression reduced images by 16.1%, saving 202 bytes.

Filename	Before	After	Improvement	Visual comparison
src/static/images/2020/css/gradient-most-stops.png	1.23 KB	1.03 KB	-16.1%	View diff

773 images did not require optimisation.

[tunetheweb]

Highlighted the TODOs for your comment.

BTW forgot to say - fantastic chapter. Very interesting and very readable even for someone like me with limited CSS knowledge (other than the colour gamut stuff that went completely over my head 😀)! So really well done given the amount you covered!

Let me know your thoughts on the points I've highlighted with TODOs and feel free to suggest changes via GitHub or to just push suggestions directly to this branch.

[svgeesus]

I notice that the advance release of the almanac used the small color table rather than the much bigger table from the >100k re-run. The difference is significant, the first run found only 23 unique pairs of (P3, sRGB) colors while the re-run found 114.
The graphic used is the correct one, with all 114 color pairs plotted.

[svgeesus]

(other than the colour gamut stuff that went completely over my head 😀)!

Sorry about that. So, this was the explanation I used (trying to keep it short, but apparently it wasn't understandable enough):

All the colors we discussed so far have one thing in common: sRGB, the standard color space for the Web (and for High Definition TV, which is where it came from). Why is that so bad? Because it can only display a limited range of colors: your phone, your TV, and probably your laptop are able to display much more vivid colors due to advances in display technology. Displays with wide color gamut, which used to be reserved for well-paid professional photographers and graphic designers, are now available to everyone. Native apps use this capability, as do digital movies and streaming TV services, but until recently the Web was missing out.

Gamut is "the range of colors that can be displayed" and a narrower gamut means less colors (omitting the more vivid ones). Suggestions to re-word that would be welcome. Maybe

"Because it has a small gamut (it can only display a limited range of colors)" makes it clearer?

Or was it the chromaticity diagram or the use of deltaE that was unclear?

I felt it was important to capture this data, despite p3 colors being barely used, because this is expected to increase over then next few years and therefore this year is the baseline to compare against.

[tunetheweb]

I notice that the advance release of the almanac used the small color table rather than the much bigger table from the >100k re-run. The difference is significant, the first run found only 23 unique pairs of (P3, sRGB) colors while the re-run found 114.
The graphic used is the correct ne, with all 114 color pairs plotted.

Could we link to this instead? I feel the full table would be quite large, and having it in a spreadsheet makes it easier to copy and paste and use fiddle with the data if you want.

Plus there's a bug in our PDF generator that doesn't like tables spanning more than one page 😀

I've copied the data to your spreadsheet and added a link to figcaption in 97d3ed5 and you can see what that looks like here: https://20201228t110002-dot-webalmanac.uk.r.appspot.com/en/2020/css#fig-29

WDYT?

Or was it the chromaticity diagram or the use of deltaE that was unclear?

I felt it was important to capture this data, despite p3 colors being barely used, because this is expected to increase over then next few years and therefore this year is the baseline to compare against.

I get the basic concept but the finer details were a little lost on me, but that's OK. What's more concerning is I didn't really get the point you were trying to make. Did you see my comment in #1846 (comment)?

You may have to click this to see the rest of my comments:

Here's what I said:

{# TODO Authors—you're completely losing me with this :-) Not sure if there's a way to simplify it more or if this is just the nature of this topic and it's just more advanced, which is fine — the rest of the chapter so far is is more than readable for those less-advance amongst us! But still not sure what your point is here? They shouldn't have used display-p3 because sRGB was good enough? Or is it more than people are just cautiously experimenting at the moment so no real gains yet, but more to come (as covered by your next bit of writing after this table? #}

[svgeesus]

What's more concerning is I didn't really get the point you were trying to make. Did you see my comment in #1846 (comment)?

I did now :)

[svgeesus]

What is the timescale for reviewing these comments?

[tunetheweb]

What is the timescale for reviewing these comments?

Depends how keen you are to remove the "Unedited" label 😁 Sooner would be better rather than later though as now is when it gets a lot of views.

We can have a look after the majority are answered/resolved/not doing and decide if it's basically edited now and and leave one or two till later.

[LeaVerou]

Removed a lot of italics and bold emphasis as felt not needed.

Italics and bold help chunking, which makes text easier to process than one blob of uniform text, and more pleasant to read. They are the typographic equivalent of formatting a long phone number with dashes and parentheses instead of presenting it as a series of numbers. It is not a good idea to remove them.

[tunetheweb]

Removed a lot of italics and bold emphasis as felt not needed.

Italics and bold help chunking, which makes text easier to process than one blob of uniform text, and more pleasant to read. They are the typographic equivalent of formatting a long phone number with dashes and parentheses instead of presenting it as a series of numbers. It is not a good idea to remove them.

Personally I disagree - that's what punctuation is for. Italics and bold are for emphasis and (IMHO) they are often overused for this. Some style guides agree, though the Google Developer Documentation Style Guide isn't quite a clear on the subject as that.

For the Web Almanac we use italics to introduce a new technical term and (very sparingly) for emphasis. We also have the "big figures" for emphasising important or interesting stats and this is better to me in that it also links back to the data and queries to back that up.

Now there is a balance between celebrating the fact we have different, and diverse authors (and so writing style!) for each chapter, and trying to have a consistency across all the chapters. That's something we try to address in the editing process and yes it does lead to tough calls and disagreement when writing styles clash. I feel this is one point we should be consistent on to avoid confusing readers when one chapter uses bold and italics for one reason, and another for another. If you look across the other chapters bold and italics are not used much at all (and only sometimes has that been because editors have removed them!)

But more than willing to admit I could have got it wrong in places, so if there's particular ones you want to bring back then please add comment in Files tab and we can discuss, but I'd personally be against bringing back all the ones I removed as I really do feel they distracted, more than helped.

I'd be interested to hear others opinion on this too (as long as you three authors don't gang up on this one poor, wannabe editor! 😀) — especially @rachelandrew given her professional editing experience.

[tunetheweb]

@svgeesus @LeaVerou @rachelandrew keen to close this out and removed the Unedited tag from the label. Could you look over the remaining open issues and see if we can merge this soon?

[rachelandrew]

@bazzadp I'll take a look at any of these things that relate to my bits.

With regard to extensive use of bold and italics, I'm not a fan, and remove them when editing. In general, if a paragraph is so long that you need to add bold to "chunk" it, it might be better to split it into two sections, add a heading or example. Quite a lot of people also find italicised text difficult to read in large blocks.

Bold and italic also infer some kind of meaning, but what? If the section needs calling out in some way it would be better to have an option to highlight it (something to make it a note, or warning perhaps). When I'm editing, if I see a section in bold, that's a flag for me to ask the author why they thought that bit was so important it should be in bold. Perhaps instead they could explain why it was so important, rather than just wave an important flag by way of emboldening the text.

[tunetheweb]

Have you had a chance to look at this yet @rachelandrew ? I really would like to close this out ASAP even if it means merging this PR and addressing the last few items in future.

[rachelandrew]

@bazzadp I didn't see anything related to the sections I had worked on. Have I missed something?

[tunetheweb]

Sorry I'm not aware of who worked on what, so was only following up on your comment when you said you'd close out anything related to your bits.

There's still a few unresolved items above but guess they are for @LeaVerou or @svgeesus then.

From your end I presume you're happy to merge this @rachelandrew and that I haven't butchered your writing too much? 😀

[LeaVerou]

@bazzadp I'll take a look at any of these things that relate to my bits.

With regard to extensive use of bold and italics, I'm not a fan, and remove them when editing. In general, if a paragraph is so long that you need to add bold to "chunk" it, it might be better to split it into two sections, add a heading or example. Quite a lot of people also find italicised text difficult to read in large blocks.

Bold and italic also infer some kind of meaning, but what? If the section needs calling out in some way it would be better to have an option to highlight it (something to make it a note, or warning perhaps). When I'm editing, if I see a section in bold, that's a flag for me to ask the author why they thought that bit was so important it should be in bold. Perhaps instead they could explain why it was so important, rather than just wave an important flag by way of emboldening the text.

I think we may be talking about different things. I do not support overuse of bold and italics, as they defeat the purpose and dilute their meaning. However, when used appropriately, they can increase scannability, reduce cognitive load, and make a paragraph easier to process. I also did not advocate for entire sections in bold.

[tunetheweb]

Thanks @LeaVerou appreciate it. It would be good to get this closed out so I can stop pestering you all! Really do appreciate the huge effort that’s gone into this already but this should hopefully be the last piece!

As I said earlier I’m happy to reintroduce any of the bolds and italics you feel are necessary if you want to make those edits in this branch. Maybe I was too aggressive removing some of them but honesty didn’t think at least some of them were necessary and think Rachel’s covered some of my thinking here. But I’ve been wrong before (and definitely will be again!) and it’s your names at the top, so want you to be comfortable with any edits made and revert any you’re not comfortable with.

[tunetheweb]

Oh and huge congrats on your election to W3C Tag!! Very well deserved!

[LeaVerou]

I just went through and left comments.

I'm not sure what kind of intro text to add to prevent adjacent headings. I suppose I'm not used to adding blurbs with no purpose just for cosmetic reasons. However, I'm fine with whatever you or anyone else wants to add.

Another issue with removing italic and bold is that it makes the implied voice of the text flat and boring.
There is a reason why emphasis (<em>) in HTML is styled as italic by default: italic denotes stress. Emphasizing (appropriate) parts of your sentences while speaking makes for a more engaging talk, while keeping a constant tone of voice makes for a dull one. It's the same with writing.

Compare this:

While analyzing CSS code tells us what CSS developers are doing, looking at preprocessor code can tell us a bit about what CSS developers want to be doing, but can't.

with this:

While analyzing CSS code tells us what CSS developers are doing, looking at preprocessor code can tell us a bit about what CSS developers want to be doing, but can't.

Read it out. Do you see the difference in tone?

I also disagree with a few of the style guide decisions, but didn't leave comments on those as I suspect it's a losing battle. But for the record:

• A "web" is something spiders make. The Web which is short for "World Wide Web" is a unique entity, a proper noun, and needs to be capitalized to distinguish it from the common noun [see also: MLA]
• "stylesheet" is far more common usage than "style sheet". 17 million results on Google for "stylesheet", 7 million for "style sheet". I've never seen anyone calling them "style sheets" except when explaining what CSS stands for. Even in HTML, it's rel="stylesheet", not rel="style sheet".

[LeaVerou]

Oh and huge congrats on your election to W3C Tag!! Very well deserved!

Thank you!

[tunetheweb]

I'm not sure what kind of intro text to add to prevent adjacent headings. I suppose I'm not used to adding blurbs with no purpose just for cosmetic reasons. However, I'm fine with whatever you or anyone else wants to add.

I made an attempt in 34ba57b

Empty or "Stacked headings" are seen as bad in writing for a number of reasons. If a number of topics are related under a heading, then there should be some relationship that can explain them. If they are unrelated then we should question if they belong under the same heading.

We can also inform the reader what is in this section without them having to refer to the index/table of contents so they know what will be covered in this section.

And finally, if you click on a heading, and immediately go to another heading then why not just go straight there?

So I tried to add some headings as I saw fit and hopefully you're OK with them. The one I did struggle with was "Meta" as wasn't use what this section was about (hence why an intro paragraph explaining it would be good! 😀) but went with:

Up until now we've looked at what CSS developers have used, but in this section we want to look more about how they are using it.

With added emphasis on how just for you! 😁

Another issue with removing italic and bold is that it makes the implied voice of the text flat and boring.
There is a reason why emphasis (<em>) in HTML is styled as italic by default: italic denotes stress. Emphasizing (appropriate) parts of your sentences while speaking makes for a more engaging talk, while keeping a constant tone of voice makes for a dull one. It's the same with writing.

Compare this:

While analyzing CSS code tells us what CSS developers are doing, looking at preprocessor code can tell us a bit about what CSS developers want to be doing, but can't.

with this:

While analyzing CSS code tells us what CSS developers are doing, looking at preprocessor code can tell us a bit about what CSS developers want to be doing, but can't.

Read it out. Do you see the difference in tone?

I do to a point, however I think the sentence gets that point across without the need of this emphasis particularly on all three words - the meaning is totalling apparent with the sentence. If you read the sentence out loud, and emphasis all three words you'll be quote out of breath by the end of the sentence.

We use italics to emphasis a new term, and very sparingly for emphasis. I left a few of those in, and added a few back in the last edit after re-reviewing, but honestly don't think it's needed in the above sentence.

And bold is a very strong emphasis - like shouting it. So it should be used very, very sparingly IMHO.

I also disagree with a few of the style guide decisions, but didn't leave comments on those as I suspect it's a losing battle. But for the record:

• A "web" is something spiders make. The Web which is short for "World Wide Web" is a unique entity, a proper noun, and needs to be capitalized to distinguish it from the common noun [see also: MLA]

I used to be with you on this and when I wrote my book I capitalised this for the reason you give but had so succumb to the publishers style guide on this. However I've changed my mind on this recently. The web is now a common, indicative part of our lives it no longer needs proper noun status in my mind and many style guides are changing to this (including the AP style guide. But there's definitely still some debate about this and it does upset some people. At the end of the day, both are used, and I think consistency is more important, and lowercase is what we've used in other chapters.

• "stylesheet" is far more common usage than "style sheet". 17 million results on Google for "stylesheet", 7 million for "style sheet". I've never seen anyone calling them "style sheets" except when explaining what CSS stands for. Even in HTML, it's rel="stylesheet", not rel="style sheet".

This one really surprised me and I actually looked it up as part of this copy edit and added it to our style guide. The Google Style Guide we use, says it uses this standard because that's what the W3C say! As some of you are in with them maybe we could get some definitive answers from them! I guess it is CSS and not CS which is one argument 😀

But it does seem to me that even then it's not clear cut: Doing a Google for "style sheet" site:https://www.w3.org/ returns 8,060 results versus 7,950 for "stylesheet" site:https://www.w3.org/ - and I suspect the majority of the ones with spaces are for Cascading Style Sheet.

So let's change here and use "stylesheet" without a space. It's what I would have used personally until I looked this up, and you backing this too convinced me. We didn't really have this standardised before (as I say I only looked it up as part of this copyedit) and doing a search the spaceless version is far more common in our codebase. Will update our style guide.

[tunetheweb]

I think this is good to merge now, so will do that before next release unless I hear back from you on anything.