Edit 2020 Markup chapter

[rviscomi]

Staging link: https://20201112t214135-dot-webalmanac.uk.r.appspot.com/en/2020/markup

Progress on #899 and #1432

Editor's notes:

• I've left inline comments (not rendered in the HTML) with annotations for editors, authors, and analysts. Not urgent but worth addressing before the full launch. For example, I've noticed a couple of sections that present stats but have no follow-up discussion or interpretation.
• One major refactor I did was to take large pieces of analysis outside of note blocks. Notes should generally be used for brief asides.
• Table headings should be more explicit about "Percentage" to specify what it's a percentage of. Replaced with "Pages (%)" when that was clearly the unit, but there are still some instances where it could be clarified.
• Added a couple of "big number" figures to highlight important individual stats not included in other figures.
• Replaced all smart quotes with plain quotes for consistency across chapters.
• Replaced capital "Web" with lowercase "web" for a bit less formality, per the guide.
• Minimized use of emdashes to only sparingly.
• Lots of wording/phrasing changes.

[j9t]

General note: This PR is too big to handle swiftly. I’ll take the preview and review the whole document now—whether I can still do so today, I’m not sure; I’ll try but this is just huge.

Then, I’d humbly and kindly ask not to “falsify” typography, for which I see three reasons:

1. It’s just wrong. We have taken great care to use the common and typographically correct apostrophes, quotation marks, and dashes, and now we use characters with entirely different (signs for feet and inches) and inaccurate meaning.

2. It distorts the review and makes it significantly harder to go through.

3. It impacts our reputation. Yes, maybe @catalinred and @iandevlin don’t care so much about this (they might—we didn’t get to talk about it yet). Yes, maybe no one notices. Yes, maybe we could also refer to you or the editors that wrong punctuation was to be used. But it is something I dislike, for my work usually stands for a certain standard, including the use of correct punctuation.

This last may sound strong, but it’s just meant to be firm. It’s nothing personal, either. I just see a lot of good work being undone here for, that’s the question (for what?)—to cost us a lot of time and likely distract us from very important things.

Thanks for considering this.

As for the review itself, I’m open to talking how we can make the timeline—if we need a compromise and this needs to go live like this, then I suggest we put up a prominent note that it’s a draft that goes live that is not endorsed by the authors yet and that may still undergo further edits. Just to have something constructive for discussion.

[j9t]

Folks, I’m going to be frank and say that I’m not very happy, even a little upset (about our situation, not about a person).

I've just read the first fifth of the chapter, and have already noted 20+ additional edits and tweaks.

I’ve invested evening after evening into getting this into a robust stage (and I know Tony and others here have done similar), and while I understand and appreciate what must have been a long session to prepare this particular PR, I do have two major concerns:

I question that all of it in here is essential (re typography, but also several modifications), and I question that most of what this PR covers couldn’t have happened before—we have been reviewing and editing for several weeks, and just as we’ve all (3 authors and 3 reviewers) are content, we get presented with a massive rewrite of the whole chapter that’s to be reviewed within a few hours (emphasis just to highlight the difference in dimensions). What I see here could and perhaps should have happened much earlier, not now.

I strongly believe we could have been smarter about this, either fully trusting the authors’ and the reviewers’ work or involving editors much earlier; and also showing a finer sense for timing, focusing on what really matters if we bundle up feedback so shortly before going public.

👉 I’m committed to getting this chapter out, but at the moment it does not have my “go.” If you like to publish it tomorrow (Nov 9), include a visible notice that it has not been cleared, endorsed, or approved yet; it would be the publisher’s version, but not (one of) the author's. [This is not super-clear but I leave it as is. The idea is, essentially, that we’re all content with the output.]

As this is heavily biting into my own schedule, too, I’ll work on carving out extra time to review the updates, provide feedback, and review again, however I don’t have more time left today, and given the amount of edits am unlikely to have feedback by tomorrow (I should be able to finish reviewing by then, however). We will probably need to coordinate as we go—given this situation and that this may throw us back a few days, it may actually be the best course of action to work with said note, that the chapter does not have final go from author/authors.

There are no bad feelings here, by the way; in fact, only constructive ones. In this complex project it was almost to be expected that we hit something… unexpected. We’ll figure something out to deal with it, and learn from it together. Let’s find a smart way to deal with what we have here.

[rviscomi]

@j9t thanks for sharing that perspective. I'll chat with the other project leads (cc @OBTo @bazzadp @paulcalvano) about possible paths forward, including your suggestions, and I'll follow up in this thread by the end of the day.

[rviscomi]

@j9t I think the fastest path to getting this launched tomorrow is a variation of your suggestion to launch with a special label. We currently support an "unedited" label for chapters that haven't gone through this final step, so let's launch it in the unedited state that it was when you merged a couple of days ago. It'll look like this:

Meanwhile, we can take our time to work through any disagreements in this PR, and reach a conclusion before the full launch on December 9. Does that sound reasonable to you? I intend to address all of the earlier points you made about the editing process in a follow-up comment, but I thought it was more important to find consensus on the time-sensitive next steps first.

[rviscomi]

I didn't even get the name of this chapter right in the PR/branch 😅

[tunetheweb]

I didn't even get the name of this chapter right in the PR/branch 😅

Man, I’m constantly confusing markdown and markup during this project!!!!

[j9t]

I reviewed the chapter, and am preparing to provide detailed feedback, likely tomorrow.

We have some more work to do here, and I’d be very happy if co-authors (@catalinred, @iandevlin) and reviewers (@zcorpan, @bkardell, @matuzo) could be on standby to also review this version again after I went through with the next sweep. I’d really appreciate it—you left some great feedback in the original draft and know the chapter as well.

[zcorpan]

Hmm, I thought the 3.86% number was of pages using <img loading=lazy>, not of img elements. If it's not % of pages, the numbers are not comparable.

[rviscomi]

cc @Tiggerito

[Tiggerito]

@zcorpan is right. This data is on a per page bases. So pages that have an img with loading set to lazy.

[iandevlin]

So the "this appears to be growing fast..." sentence should be removed?

[rviscomi]

I've corrected the phrasing of the stat itself but left a TODO for the authors to update their interpretation.

[zcorpan]

@iandevlin no it can stay, since both stats are of pages.

[tunetheweb]

I've raised a separate issue on smart quotes with much more detailed reasoning in #1485 . Let's take any further discussion on whether to change that (in the future - well after this PR is merged), over to there.

[rviscomi]

The unedited version of this chapter was published on November 9. Reopening this PR for review so we can use the remaining time until full launch on December 9 to wrap up the remaining edits.

[j9t]

I added everything I noticed.

I heavily prioritize the content side now, so thanks for understanding: Could you provide another preview once all edits are done? I think we need at least another sweep.

[zcorpan]

Did we want to mention the 3.97% quirks mode stat in the "Doctypes" section? Maybe put it in the table as "No doctype or any quirky doctype"

[rviscomi]

All comments have been resolved with changes or TODOs. The team can work at their own pace to resolve the remaining TODOs, targeting the full launch on December 9. I've kept the "unedited" flag set for this chapter so if these changes do get pushed live between now and then, readers understand that we're still working on it.

If that sounds good, I'll wait for @j9t's approval before merging. LMK if anyone has any other feedback.

[j9t]

Sounds all good to me. Special thanks to you, @rviscomi and @bazzadp, for preparing this update!

[tunetheweb]

Good stuff @j9t and thanks for agreeing to merge this. I think there are good improvements here that will make it clearer to readers and also standardise it to give the whole Almanac a consistent style.

We’ve still some things to fix but as this chapter is pretty close I’d suggest we all take a (small!) break to get all our heads out of this for a bit and approach it with fresh eyes in a week or so. So after that can the authors lead the charge on submitting a PR with the TODO fixes and then we can give it another once over with an editors eye on it?

What’s clear from this is that we’re all passionate about delivering the best chapter here — even if we have slight disagreements about what exactly that means! That’s a great thing and means the end result will be the best we can all produce together, which can only benefit the reader and the project as a whole.

Thanks again for the whole team’s work on this, including @rviscomi for doing the edits so far.

[iandevlin]

Thanks everyone for all your work on this. I am also happy to see this merged.