Markup 2022
rviscomi opened this issue · comments
Markup 2022
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 |
|---|---|---|---|---|---|
| @rviscomi | - | @siakaramalegos |
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 1: The content team has at least one author, reviewer, and analyst
1. Plan content
- May 15 The content team has completed the chapter outline in the draft doc
2. Gather data
- June 1: Analysts have added all necessary custom metrics and drafted a PR (example) to track query progress
- June 1 - 15: HTTP Archive runs the June crawl
3. Validate results
- August 1: Analysts have queried all metrics and saved the output to the results sheet
4. Draft content
- September 1: The content team has written, reviewed, and edited the chapter in the doc
5. Publication
- September 15: The completed chapter and all required metadata and figures are converted to markdown and submitted to GitHub
- September 26: Target launch date 🚀
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
I think I'd like to take this up again this year as an author.
Happy to review.
Would love to contribute to this again this year, however I can.
@AlexLakatos are you ok being the content lead as well?
Sure!
I can co-author here.
@ibnesayeed that would be great, thanks!
I'm happy to help author web components related sections and review overall
@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.
Tentatively adding myself as the analyst for this chapter to help it meet Milestone 0.
@siakaramalegos @daKmoR I'm cool with having multiple authors, welcome to the team!
@rviscomi thanks for volunteering, welcome to the team!
@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
@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!
@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.
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?
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!
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.
✨ 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! 😁
@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.
FYI coauthors and reviewers @AlexLakatos @ibnesayeed @daKmoR @j9t @bkardell: the analysis PR #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)
@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.
🛎️ @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!
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
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.
Still planning on writing this. We can revisit next week if my hopes and dream will translate into reality or not.
@AlexLakatos The deadline is in 5 days so if you can't commit to it then maybe one of the other authors should start?
⛔ 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.
@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.
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.)
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.
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.
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!)
Rick owns all the sheets. So just request access and he’ll action as soon as he can.
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.
Updated the draft and would like to hand over for review to @bkardell (and @zcorpan, if you’re in).
Made the following changes:
- Edited and cleaned up
- Reworked the top elements section
- Added some pull quotes
- Added a section on social markup
- Made the spreadsheet more consistent and easier to work with (as with hiding empty columns), given that the chapter encourages review of the data
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.)
- @bkardell, can I hand over to you for review?
- @rviscomi, also @siakaramalegos and @tunetheweb, are we good, does this work?
- 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.
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.
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.
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!).
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).
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.)
@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.
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...
-
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?
-
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.
@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.)
@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.
@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?
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.
@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.
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.