search

HTTPArchive / almanac.httparchive.org

HTTP Archive's annual "State of the Web" report made by the web community
https://almanac.httparchive.org
Apache License 2.0
611 stars 170 forks source link

Markup 2022 #2881

Closed rviscomi closed 2 years ago

rviscomi commented 2 years ago

Markup 2022

Markup illustration

If you're interested in contributing to the Markup chapter of the 2022 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~ @j9t ~@AlexLakatos @ibnesayeed @daKmoR~ @j9t ~@j9t~ @zcorpan @bkardell @rviscomi - @siakaramalegos
Expand for more information about each role 👀 - The **[content team lead](https://github.com/HTTPArchive/almanac.httparchive.org/wiki/Content-Team-Leads'-Guide)** is the chapter owner and responsible for setting the scope of the chapter and managing contributors' day-to-day progress. - **[Authors](https://github.com/HTTPArchive/almanac.httparchive.org/wiki/Authors'-Guide)** 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](https://github.com/HTTPArchive/almanac.httparchive.org/wiki/Reviewers'-Guide)** are also subject matter experts and assist authors with technical reviews during the planning, analyzing, and writing phases. - **[Analysts](https://github.com/HTTPArchive/almanac.httparchive.org/wiki/Analysts'-Guide)** 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](https://github.com/HTTPArchive/almanac.httparchive.org/wiki/Editors'-Guide)** 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](https://github.com/HTTPArchive/almanac.httparchive.org/wiki/Section-Leads'-Guide)** 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](https://github.com/HTTPArchive/almanac.httparchive.org/wiki/Chapter-Lifecycle) doc.

Milestone checklist

0. Form the content team

1. Plan content

2. Gather data

3. Validate results

4. Draft content

5. Publication

Chapter resources

Refer to these 2022 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 💬 #web-almanac-markup on Slack for team coordination

AlexLakatos commented 2 years ago

I think I'd like to take this up again this year as an author.

j9t commented 2 years ago

Happy to review.

bkardell commented 2 years ago

Would love to contribute to this again this year, however I can.

siakaramalegos commented 2 years ago

@AlexLakatos are you ok being the content lead as well?

AlexLakatos commented 2 years ago

Sure!

ibnesayeed commented 2 years ago

I can co-author here.

AlexLakatos commented 2 years ago

@ibnesayeed that would be great, thanks!

daKmoR commented 2 years ago

I'm happy to help author web components related sections and review overall

siakaramalegos commented 2 years ago

@daKmoR Typically you're a co-author or a reviewer, but not listed as both. As a co-author, you still get to review all the content and provide feedback, you just only get one credit for it (author or reviewer).

Once content leads are selected (@AlexLakatos) they get to pick the final authoring team. So I'll let you two chat and then Alex can update the issue with the final decision.

rviscomi commented 2 years ago

Tentatively adding myself as the analyst for this chapter to help it meet Milestone 0.

AlexLakatos commented 2 years ago

@siakaramalegos @daKmoR I'm cool with having multiple authors, welcome to the team! @rviscomi thanks for volunteering, welcome to the team!

AlexLakatos commented 2 years ago

@daKmoR @ibnesayeed @j9t @bkardell @rviscomi Don't forget to add your contact info to the tracking document: https://docs.google.com/document/d/1OV_-YmxXoFCalDIdAYq9eTZMpjsQ0rsuFKGAsF-8eoM/edit#heading=h.xleqpbggrlck

rviscomi commented 2 years ago

@AlexLakatos @ibnesayeed @daKmoR @j9t @bkardell looks like there hasn't been much progress on the chapter outline yet. Could you all make sure you have access to the doc and start adding your ideas for new things happening to Markup this year, or interesting topics to revisit from previous years? Hoping to have that completed by May 15 to give us enough time to implement any needed custom metrics before the June crawl begins. Thanks!

siakaramalegos commented 2 years ago

@AlexLakatos @ibnesayeed @daKmoR @j9t @bkardell just a reminder that the outline is due in 2 days. Please open the doc, add your name and email address to confirm your participation, and add your thoughts for the outline.

This is a critical deadline because we only have 2 more weeks to finalize any custom metrics for the crawl.

daKmoR commented 2 years ago

I started an outline based on the one from last year - feel free to adjust/add/remove...

I tried to add some details on what to capture - not sure if it makes sense or what format it should be? any hints on how to formulate it?

AlexLakatos commented 2 years ago

We can use the metrics from last year as well. I've only added a couple of new things for links. @daKmoR I've seen the new web component sections you've added, looks good!

AlexLakatos commented 2 years ago

I've just marked the content plan as complete, it's got a lot of the things from last year, with just a few things added on around web components and links for this year. @rviscomi we can go ahead and look at the new metrics that need to be added, there's only a couple of things.

rviscomi commented 2 years ago

✨ Custom metrics added! We're all caught up on the analysis milestones, so the next step is to wait for the June crawl to kick off and start drafting the queries in #2945. Then it's over to you @AlexLakatos to do the fun part! 😁

rviscomi commented 2 years ago

@AlexLakatos FYI I'm starting to write the queries and putting the results in the chapter spreadsheet. I'll let you know when it's done but you can start taking a look now to plan your narrative.

Update: analysis is done. Just waiting for a code review on #2945, but you should be unblocked to review the results and start writing.

rviscomi commented 2 years ago

FYI coauthors and reviewers @AlexLakatos @ibnesayeed @daKmoR @j9t @bkardell: the analysis PR https://github.com/HTTPArchive/almanac.httparchive.org/pull/2945 is merged so it's over to you all now to review the results and start drafting the content. Let me know in the comments of the spreadsheet if you have questions about anything! (you will need to request edit access, as usual)

siakaramalegos commented 2 years ago

@AlexLakatos when do you think you can begin the draft? Just as a reminder, the due date at the end of the month is for post-review and post-edit, so you'll need to set aside at least a week for those and preferably more.

rviscomi commented 2 years ago

🛎️ @AlexLakatos @ibnesayeed @daKmoR @j9t @bkardell the results have been ready for two months but I don't see any progress whatsoever in the draft doc. As @siakaramalegos noted, the chapter is expected to be written, reviewed, and edited by the end of the month.

@AlexLakatos as the chapter lead please coordinate with your team to get the draft written. There are three coauthors so they should each have sections assigned to work in parallel. Reviewers should be kept in the loop so they can make time to give feedback when the draft is ready. There is not currently an editor assigned but as soon as the draft is reviewed, reach out to @siakaramalegos and we'll find someone.

We're almost done!

siakaramalegos commented 2 years ago

Haven't seen any update in the draft doc so wanted to reach out again - @AlexLakatos when do you think you can begin the draft? What's the plan to complete it in time? Thanks

siakaramalegos commented 2 years ago

Hi all, Rick and I haven't seen any responses to our messages and the deadline is upon us. Is anyone going to work on writing this chapter by the end of the month? If not, then this chapter is at risk of being closed so that we can focus our effort on the other chapters.

@AlexLakatos @ibnesayeed @daKmoR @j9t @bkardell

AlexLakatos commented 2 years ago

Still planning on writing this. We can revisit next week if my hopes and dream will translate into reality or not.

siakaramalegos commented 2 years ago

@AlexLakatos The deadline is in 5 days so if you can't commit to it then maybe one of the other authors should start?

rviscomi commented 2 years ago

⛔ Hi everyone. Given that we're now beyond the deadline to have the draft written, reviewed, and edited but the draft has still not been started, unfortunately I think we're going to have to close the chapter. It's not looking like it'll be feasible to get the chapter back on track to be able to launch on time. Apologies to everyone who committed their time up to this point, and thanks for your understanding.

j9t commented 2 years ago

@rviscomi, @siakaramalegos, team—if you can give me 5 days (until Wed, Sep 7) and allow to keep this chapter short, I think I can turn it around and write a minimum chapter until then, to be handed over for review.

(That assumes that the data are good—they seem so, but if there are major issues here, that could still stop us.)

Please confirm asap and I get right at it.

@bkardell, would you still be available as a reviewer? @zcorpan, I know you didn’t raise a hand, but would you be open to reviewing, too? Would be delighted to pair up with you.

j9t commented 2 years ago

PS. I may need support for generating the charts (will leave notes with sufficient detail in the doc to aid this process) as well as for Markdown conversion. I hope that’s work we can share across a few people.

(Background is that I’m on vacation Sep 8–23. Will work during the time, but also need some time off, and may communicate with light delay. Therefore being upfront about this part, too.)

tunetheweb commented 2 years ago

Charts in sheet look good to me. I'm able to help change them if you want a different format. I'm also able to help convert to Markdown.

j9t commented 2 years ago

Awesome, thanks @tunetheweb!

Reviewed the chapters of the last years and added a draft outline.

Reviewing data.

@rviscomi, @siakaramalegos, team—preparing to go full steam.

j9t commented 2 years ago

Was briefly in touch with @rviscomi—feeling free to proceed, that way we don’t lose any of the little time this may still have.

(Can someone give me edit, at least comment rights, to the data sheet? Thanks!)

tunetheweb commented 2 years ago

Rick owns all the sheets. So just request access and he’ll action as soon as he can.

j9t commented 2 years ago

This didn’t let go of me so I completed the first draft (~13 pages).

I’ll review this myself now, likely edit a little, and maybe even add to this.

Will follow up again tomorrow to coordinate the next steps.

j9t commented 2 years ago

Updated the draft and would like to hand over for review to @bkardell (and @zcorpan, if you’re in).

Made the following changes:

I maintain a small list of things I may want to add over the next few days (internal ref: comments, SVG, embedded elements, favicons), but these are minor and I like to keep this entirely optional. (If I do add new sections or subsections, I’ll mark them and ask for review just for these sections.)

  1. @bkardell, can I hand over to you for review?
  2. @rviscomi, also @siakaramalegos and @tunetheweb, are we good, does this work?
  3. What’s the next step after review—converting to Markdown and preparing the respective PR? Who could take care of that?

In general, I’ll walk this chapter to the finish line, but ideally soon coming from a supporting role. (I’m busy with work before taking off for vacation on Thu, Sep 8. Will be able to do light tasks during the time off.) Any help is therefore appreciated so that we shoulder the remaining work together.

tunetheweb commented 2 years ago

Looks good to me. A little shorter all right, but in all honesty maybe that's no harm. Need to decide how to frame that though as currently it feels a little apologetic which I worry means the chapter won't be taken as seriously. So think we should tone some of that down a little. Left that, and a few other comments.

j9t commented 2 years ago

Awesome, thanks @tunetheweb! Just went through your feedback.

As for the framing, I welcome thoughts on it sounding factual rather than apologetic. It’s important to me that there is this framing, however, because with more time, I would have loved to analyze and cover more data, with the team.

tunetheweb commented 2 years ago

Understand. And appreciate it’s your name on it and it was completed in a rush.

Just want to balance that with making it sound like it’s a rush-job (which I appreciate it actually is) and therefore a sub-standard chapter (which it isn’t IMHO given your expertise and the analysis run - even if it’s not as in depth as it would have been if you’d been authoring from the beginning). I just want to make sure it doesn’t reflect badly on the Web Almanac project.

But am sure we can come up with something to keep everyone happy. Will mull it over and see what others think too. Maybe I’m over thinking it (wouldn’t be the first time!).

zcorpan commented 2 years ago

The Introduction and Conformance focus more on what is not included, which I think seems better to talk about towards the end, if at all.

2021 had a section dedicated to the doctype, which I think would be nice to have this year also. And mention year-over-year changes (88.8% to 90% for <!doctype html>). No doctype wasn't mentioned in 2021, but it's in the results (2.5% for mobile).

j9t commented 2 years ago

Thank you so much, @zcorpan! 🙏 Much appreciated you taking the time.

Will have a look at intro and conformance again, but now getting tricky on my end (completely packed until my departure).

For doctype infos, thanks for the pointer! I augmented the respective paragraph with 2021 data. (Maybe I get to make this a full section, too, but unclear at this point.)

siakaramalegos commented 2 years ago

@j9t thank you so much for stepping up and getting this content written.

Re: the editor's note... If you keep that content, it highlights and emphasizes the perception that the content is not quality. In my experience, if you don't apologize, people usually do not notice any of your perceived shortcomings. To state another way, adding the apology will reflect poorly on the post. Removing it will increase positive quality perception.

I have not read this chapter in previous years. In my opinion, the only section that seems slightly short is the introduction. I'd just duplicate your findings in the intro, worded slightly differently from the conclusion. Remember, short doesn't equal bad. It's just more clear and concise.

bkardell commented 2 years ago

Just ran through this fairly quickly, but mainly my comments are about the same as the others. Generally, seems fine.

A few maybe interesting things to look at or consider if you have any time...

  1. You talk about HTML and valid names, SVG/MathML and custom elements, and some deprecated elements - but a point that I think is also interesting is what about just unknown elements in the global space. https://rainy-periwinkle.glitch.me/permalink/2b13e0baf16fa5aa3814349042efb110c9b7d0aee7c84b704a26360033a02907.html is some data on elements that are part of none of those other groups but also don't contain a dash. If you scroll way way down to the summary details there are some numbers for each in there - some of which are pretty huge (approaching 80k sites?!), and many of those also line up with the ones in the 2019 data irc. Might be interesting to say something about that and what that tells you about the data or practices, perhaps?

  2. I have been trying to track 'popular' elements regularly in datasets - that tool will also give you a few views like https://rainy-periwinkle.glitch.me/popular/mobile which is pretty interesting as a way to see what ones are "growing" uses - though, it's dramatically flawed in a way because the size of the sets change or whatever and a small reduction for a month doesn't necessarily mean it is an indicator that it is no longer growing, for example. Idk if there is anything interesting in that to you at all.. But if it is and you want to talk lmk.

j9t commented 2 years ago

@bkardell, thank you for reviewing…! This is great.

The points you share would be interesting to review indeed. On scanning, the unknown elements seem to reflect a few past techniques, which could add value to discuss. Thanks! (I can’t commit to more at this point, but will keep it in mind.)

j9t commented 2 years ago

@siakaramalegos, team, on the introductory note, please take care of this in a manner that acknowledges the difference between having 100 days to write and having 1 day to write the chapter, so as to maintain some fairness in this situation. That’s all I’m asking for. Thanks.

rviscomi commented 2 years ago

@j9t first of all thank you for stepping up to ensure that this chapter makes it to publication this year. I definitely appreciate that you wrote the draft at lightning speed under the less than ideal circumstances.

I agree with everything @siakaramalegos said about the disclaimer. I'll also emphasize that our editorial standards haven't changed. If we're going to publish this chapter, it's because we think it's high quality and deserving of readers' attention. However, if you feel in any way like the length/quality of the chapter reflects poorly on you as the author, then we need to resolve that by either: not publishing something you wouldn't be comfortable putting your name on, or spending more time to get it into better shape. Delaying the release by one or two weeks is an option if time is the issue—this isn't the only chapter that'll be delayed. How does that sound?

j9t commented 2 years ago

Why do you need to emphasize that your standards haven’t changed? Make the criteria harder for me.

There’s no contradiction in delivering something solid and stating that under other circumstances, one would have approached it differently and may have produced more or better. There’s nothing wrong with that, and there’s nothing immodest about that, either. Everyone gets it. 100 days vs. 1 day. Not as easy to communicate (editor problem, readers may not care), but possible.

But pushing back on a brief truthful note, pointing to standards, and extending time for something that was days ago marked as having run out of time, to someone who delivered the work and stated they have no time to work further because they’re ooo, is not empathetic. It’s not meant like that, but it adds insult to injury.

You could also decide to have mine and other authors’ backs on something like this. “Thanks x—we got this.”

The chapter I handed to you is good. I’m happy to sign it with my name. I could have still produced more and better. With a team we could have produced more and better. I don’t have more time. We don’t have more time. That’s the situation. Given the circumstances, not a bad one. Actually, quite a good one.

I’ll work with you on getting the chapter out for release. This matter I don’t want to discuss any further—I like and respect you and the team, and this starts to upset me. It’s a problem, but I trust you and team to find a solution. Not for me, but for everyone who helps you out at the very last minute. (Maybe just mark them with a lightning symbol!—“emergency rescue team” or something. Good enough!) If you look at it, the ultrashort timeframe is by itself a higher standard.

j9t commented 2 years ago

@rviscomi, @siakaramalegos, moving to the chapter itself: What is best to happen next—editing or Markdown conversion? (It seems editing falls into stage 4. though, so probably that?)

Just FYI: I’m going to review the doc once more while in transit, and if possible add to it (thanks again @zcorpan and @bkardell for feedback!). That can’t and shouldn’t make anyone wait though, so I’d love to hand over so that this can run its course.

AlexLakatos commented 2 years ago

I'm sorry for massively dropping the ball on this one. I've read through the chapter though, and it reads really well in this shortened form.