Markup 2021

[rviscomi]

Part I Chapter 3: Markup

If you're interested in contributing to the Markup chapter of the 2021 Web Almanac, please reply to this issue and indicate which role or roles best fit your interest and availability: author, reviewer, analyst, and/or editor.

Content team

Lead	Authors	Reviewers	Analysts	Editors	Coordinator
@AlexLakatos	@AlexLakatos	@j9t @ibnesayeed @meyerweb @brycehowitson	@kevinfarrugia	@shantsis	@rviscomi

Expand for more information about each role

• The content team lead is the chapter owner and responsible for setting the scope of the chapter and managing contributors' day-to-day progress.
• Authors are subject matter experts and lead the content direction for each chapter. Chapters typically have one or two authors. Authors are responsible for planning the outline of the chapter, analyzing stats and trends, and writing the annual report.
• Reviewers are also subject matter experts and assist authors with technical reviews during the planning, analyzing, and writing phases.
• Analysts are responsible for researching the stats and trends used throughout the Almanac. Analysts work closely with authors and reviewers during the planning phase to give direction on the types of stats that are possible from the dataset, and during the analyzing/writing phases to ensure that the stats are used correctly.
• Editors are technical writers who have a penchant for both technical and non-technical content correctness. Editors have a mastery of the English language and work closely with authors to help wordsmith content and ensure that everything fits together as a cohesive unit.
• The section coordinator is the overall owner for all chapters within a section like "User Experience" or "Page Content" and helps to keep each chapter on schedule.

Note: The time commitment for each role varies by the chapter's scope and complexity as well as the number of contributors.

For an overview of how the roles work together at each phase of the project, see the Chapter Lifecycle doc.

Milestone checklist

0. Form the content team

• May 31: The content team has at least one author, reviewer, and analyst

1. Plan content

• June 15 The content team has completed the chapter outline in the draft doc

2. Gather data

• June 30: Analysts have added all necessary custom metrics and drafted a PR (example) to track query progress

• July 1 - 31: HTTP Archive runs the July crawl

3. Validate results

• September 30: Analysts have queried all metrics and saved the output to the results sheet

4. Draft content

• October 31: The content team has written, reviewed, and edited the chapter in the doc

5. Publication

• November 15: The completed chapter and all required metadata and figures are converted to markdown and submitted to GitHub

• December 1: Target launch date 🚀

Chapter resources

Refer to these 2021 Markup resources throughout the content creation process:

📄 Google Docs for outlining and drafting content
🔍 SQL files for committing the queries used during analysis
📊 Google Sheets for saving the results of queries
📝 Markdown file for publishing content and managing public metadata

[j9t]

Interested and available as a reviewer. (Co-author, too, on demand.)

[rviscomi]

Thanks @j9t! Added you as a reviewer.

[tunetheweb]

BTW we got a suggestion from @axelboc in #1954 which might be one to consider for this chapter:

I'd be interested to know the proportion of explicit vs. implicit labelling of form elements.

The presence of the for attribute on label elements would be a good first indicator. However, to go further, the query could check:

• whether both explicit and implicit labelling are used together,
• whether the IDs referenced in the for attributes actually exist,
• what kind of labelable form elements are more likely to be explicitly vs implicitly labelled (or not labelled at all even?) - e.g. perhaps checkbox and radio buttons are more likely to be implicitly labelled for styling purposes?

Explicit vs. implicit labelling vs. both

[rviscomi]

📟 paging 2019/2020 contributors: @bkardell @zcorpan @tomhodgins @matthewp @catalinred @iandevlin @matuzo @Tiggerito

Would any of you be interested to contribute to the 2021 chapter? I'd especially like to see more 2019/2020 authors become 2021 reviewers to help ease the transition and similarly I think prior reviewers would make great 2021 authors, being familiar with the process already. And prior analysts would make excellent 2021 analysts 😁

Or is there anyone new you'd like to see?

[Tiggerito]

I don't have the time to give this year, but I could support a new Analyst in getting up to speed.

[rviscomi]

@meyerweb were you interested in being an author or reviewer of this chapter? Also pinged you in the CSS chapter, LMK if you'd be interested in either/both.

[rviscomi]

@jabranr were you interested in reviewing this chapter? (or JS/CSS)?

[ibnesayeed]

I can review this chapter!

[matuzo]

I’d love to contribute again, but unfortunately I don’t have the time this year.

[jabranr]

@jabranr were you interested in reviewing this chapter? (or JS/CSS)?

@rviscomi I can go for JS/CSS ones.

[tomhodgins]

I'm curious/willing to help with a CSS chapter in whatever way helps! Cheers, Tommy

…

On May 7, 2021, at 1:39 PM, Jabran Rafique⚡️ ***@***.***> wrote: @jabranr <https://github.com/jabranr> were you interested in reviewing this chapter? (or JS/CSS)? @rviscomi <https://github.com/rviscomi> I can go for JS/CSS ones. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#2142 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAHJJULL7GQTBJ63XG6NM7DTMQQTXANCNFSM43UFMHVQ>.

[meyerweb]

Sorry for the delay. I can definitely commit to being a reviewer for Markup as well as CSS. Still running the idea of authoring past my team at work.

[rviscomi]

I can go for JS/CSS ones.

@jabranr ok great! Could you comment on the JS and/or CSS issues for whichever you're interested in?

I'm curious/willing to help with a CSS chapter in whatever way helps!

@tomhodgins great! Could you reply to the CSS issue and indicate whether you're interested in authoring/reviewing/analyzing?

Sorry for the delay. I can definitely commit to being a reviewer for Markup as well as CSS. Still running the idea of authoring past my team at work.

@meyerweb per our Slack chat, I'll add you as a reviewer here and content team lead (author) for the CSS chapter. Great to have you!

[rviscomi]

@j9t if no one else is interested, would you be willing to take on the content team lead and author roles for this chapter?

[j9t]

Hi @rviscomi—I’d love to, alas I won’t have the bandwidth this year. I’m happy to go beyond reviewing though, to assist the chapter lead as much as I can.

[brycehowitson]

I'd help as a reviewer or contribute where I can (Markup or CSS). Though I hesitate to take a huge role as I'm new to the process/time commitments.

[rviscomi]

Welcome @brycehowitson! I've added you as a reviewer for the Markup chapter. As we continue looking for a lead for the team, you can get started by requesting edit access to the draft doc and adding your ideas.

[tunetheweb]

Any interest @matuzo ?

[AlexLakatos]

Just saw the tweet, I'd be happy to take on the author slot.

[rviscomi]

@AlexLakatos thanks for your interest in authoring this chapter! As the content team lead, you'll be responsible for the scope and direction of the chapter and keeping it on schedule. We automatically monitor the staffing and progress of each chapter based on the state of the initial comment so please keep that updated as you add new contributors and meet each milestone.

We've created a Google Doc for this chapter, which you're encouraged to use to collaborate with the content team on the initial outline, metrics, and ultimately the final draft.

Next steps for this chapter are:

• Due May 31: Complete Milestone 0: Form the content team to find an analyst and add any additional coauthors/reviewers as needed
• Due June 15: Complete Milestone 1: Plan content to brainstorm content ideas in the doc (you'll need to request edit access)

There's not currently a section coordinator for this chapter, so I'll be periodically checking in with you directly to make sure the chapter is staying on schedule. Reach out here in this issue if you have any questions about the process.

More information about the content team lead and author roles and responsibilities are available for reference in the wiki if needed.

To anyone else interested in contributing to this chapter, please comment below to join the team!

[rviscomi]

Thanks for the update @kevinfarrugia! @AlexLakatos have you had a chance to start reviewing the results?

[AlexLakatos]

Not yet, but I think I'll get to them this week.

[j9t]

Hi @AlexLakatos, is there something the reviewers can currently do? Would we have a few days to go over the material; anything else that could be good for you and for us as reviewers?

[kevinfarrugia]

Hi @AlexLakatos how's it coming along? Do you need my input on any of the queries or results?

[AlexLakatos]

@kevinfarrugia It's coming slower than I anticipated, but I hope to finish this weekend. Most queries were straightforward. I could use a second pair of eyes on the "Compression" section. I used filtering on the "content_encoding" sheet to come up with the data, I could use someone double-checking if that's the right way to do it.

[kevinfarrugia]

I created a pivot table for the content_encoding sheet and a bar chart. I'm not sure if that's what you want to show. Let me know if that helps you.

content_encoding	desktop	mobile
gzip	62.85%	63.84%
br	21.75%	21.93%
	15.26%	14.11%
deflate	0.10%	0.10%

[AlexLakatos]

@kevinfarrugia That's better than what I had in mind, thanks!

[rviscomi]

@AlexLakatos how's it going? Looks like there's still a lot of writing to go. Are you mostly blocked on the data visualization part? Let me know if I can help with that.

Given the short time remaining it's highly likely that this chapter will not be fully written/reviewed/edited in time for the November 15 milestone, so let's start thinking about a more realistic timeline. @AlexLakatos can you commit to having the first draft ready for review by the 15th? We can give the reviewers a week to submit their feedback and get it resolved. That leaves only a few days to get the markdown into shape before publication. I can't guarantee that we'll have time for a formal editing pass before that though, so it may have the scarlet "unedited" badge initially, but the most important thing is to get the chapter out there for the rush of traffic after launch. So the timeline would be:

November 15: @AlexLakatos finishes the first draft (ideally straight to markdown to save time)
November 22: @j9t @ibnesayeed @meyerweb @brycehowitson finish their review
November 24: @AlexLakatos resolves all reviewer feedback and submits the markdown PR
(Editing if possible)
December 1: Launch

[AlexLakatos]

I think we can make that happen, I will try to make it happen faster than the 15th, but I don't want to over-commit again, so let's keep it the 15th. The big blocker is not visualization, though I could use help with those, I haven't figured out how to generate those yet. I'll leave comments in the doc for them.

[rviscomi]

Hi @AlexLakatos, have you been able to make any progress on the draft this week? Do you still think you can get it written by Monday?

[rviscomi]

@AlexLakatos could you give us a status update?

[AlexLakatos]

Made a decent dent into it, there are two chapters left, which I hope to complete today. In the meantime, I think we can start reviewing what's there.

[AlexLakatos]

4680 words later, I'd say the first draft of the Markup chapter is done. Happy reviewing! I'll run Grammarly on it in the morning. @j9t @ibnesayeed @meyerweb @brycehowitson, I'd love it if you took advantage of the suggestions feature of GDocs while reviewing! Let me know if you have any questions during the review.

Also, if anyone identifies an opportunity to swap some of the tables for charts, please go for it, I do feel like I've favored tables for some reason.

[j9t]

On it. Aware of the urgency, probably need this weekend to give feedback.

[tunetheweb]

I've made lots of suggestions for charts. I think they are much better (and colourful!) than table after table and table and more consistent with other chapters.

We also should move away from giving absolute numbers. Saying an element is used 3,055,068 times is meaningless without the context (which a % gives) and also makes it really difficult to compare year on year numbers since the number of websites we crawl changes continually (it's based on usage in previous months so is constantly changing - usually increasing!).

I've also rerun a lot of your queries and updated the sheets. Many of the queries were ordering by client, and then cutting off at 100 rows or similar, meaning you only got the desktop data back as the mobile results were outside that 100 limit. I've switched the queries to order by percentage descending to avoid this. @kevinfarrugia FYI

[AlexLakatos]

Thank you @tunetheweb for the charts, they are great!

[j9t]

Finished reviewing and providing feedback. Overall nice work, exciting to see this!

[AlexLakatos]

I've finished going through the reviews, thank you all for the comments and suggestions. There are a handful of discussions that could benefit from a response, would appreciate if we could wrap those up.

[rviscomi]

@AlexLakatos @j9t @ibnesayeed @meyerweb @brycehowitson @bkardell @shantsis I see there are still some open comments in the doc. Could you all take a look to see if you can resolve any of them? (some are for reviewers, and others for the author)

We should start the submission process and get this converted to markdown ASAP to get merged in time for launch, hopefully with enough time to give it a copyediting pass.