Markup 2020

[foxdavidj]

Part I Chapter 3: Markup

Content team

Authors	Reviewers	Analysts	Draft	Queries	Results
@j9t @catalinred @iandevlin	@zcorpan @matuzo @bkardell	@Tiggerito	Doc	*.sql	Sheet

Content team lead: @j9t

Welcome chapter contributors! You'll be using this issue throughout the chapter lifecycle to coordinate on the content planning, analysis, and writing stages.

The content team is made up of the following contributors:

• Authors
• Reviewers
• Analysts

New contributors: If you're interested in joining the content team for this chapter, just leave a comment below and the content team lead will loop you in.

Note: To ensure that you get notifications when tagged, you must be "watching" this repository.

Milestones

0. Form the content team

• Jul 6th: Project owners have selected an author to be the content team lead
• Jul 13th: The content team has at least one author, reviewer, and analyst (minimally viable team formed)

1. Plan content

• Jul 20th: The content team has completed the chapter outline in the draft doc
• Jul 27th: Analysts have triaged the feasibility of all proposed metrics

2. Gather data

• Jul 27th: Analysts have added all necessary custom metrics and drafted a PR to track query progress

• Aug 1 - 31: August crawl

• Sep 7th: Analysts have queried all metrics and saved the output to the results sheet

3. Validate results

• Sep 14th: The content team has reviewed the results sheet

4. Draft content

• Nov 12th: Authors have completed the first draft in the doc
• Nov 26th: The content team has prototyped all data visualizations

5. Publication

• Nov 26th: The content team has reviewed the final draft, converted to markdown, and filed a PR to add it to the 2020 content directory

• Dec 9th: Target launch date

[borisschapira]

I'm afraid I'm not fluent enough in English to create the content. I can help reviewing, though.

[j9t]

I’m happy to contribute to this. With my current workload the least I can commit to is reviewing—I look forward to coordinating with whoever would be driving this section.

[ibnesayeed]

I can review this chapter.

[catalinred]

I'd love to help in any way.

[zcorpan]

I can contribute with ideas for things to query, and review.

[iandevlin]

I would be happy to contribute and/or review.

[foxdavidj]

@j9t thank you for agreeing to be the lead author for the Markup chapter! As the lead, you'll be responsible for driving the content planning and writing phases in collaboration with your content team, which will consist of yourself as lead, any coauthors you choose as needed, peer reviewers, and data analysts.

The immediate next steps for this chapter are:

1. Establish the rest of your content team. Several other people were interested or nominated (see below), so that's a great place to start. The larger the scope of the chapter, the more people you'll want to have on board.
2. Start sketching out ideas in your draft doc.
3. Catch up on last year's chapter and the project methodology to get a sense for what's possible.

There's a ton of info in the top comment, so check that out and feel free to ping myself or @rviscomi with any questions!

[foxdavidj]

@matuzo we'd still love to have you contribute as a peer reviewer or coauthor as needed. Let us know if you're still interested!

@iandevlin @catalinred @ibnesayeed @zcorpan @iandevlin I've put you down as reviewers for now, and will leave it to @j9t to reassign at his discretion

[j9t]

Thanks @OBTo—I’m excited to work on this together with all of you who have also expressed interest! 🙏

👉 @iandevlin, @catalinred, @ibnesayeed, @zcorpan, @iandevlin, @matuzo, can you confirm that and how you’d like to be involved? Who would also like to write and co-author, who would like to cover analysis? I like the idea of forming a really strong team together. (Feel free to respond here but also directly through email, as per my profile.)

(If everyone of you is aboard, and if we can split the responsibilities well I think we already have a good setup. I’d wait until all of you confirmed to decide with you whether that’s the case or whether we need more support.)

👉 Do you have preferences for how to coordinate? Not everything will be useful to discuss in this thread; I’m not sure there is or that we need a Slack channel; maybe an email list does; what do you think and prefer?

—For my status, I’m going to take a few days to review what we have (notably docs and 2019 chapter), and will follow up here. (I’m off from July 5–9, then, when I’m going to be slow or unavailable to respond to messages.)

[iandevlin]

Hi @j9t! I would also like to co-author, if possible. As for communication, happy to use whatever, although I do find Slack verfy useful (I use it all the time these days)

[catalinred]

Hi @j9t,

I made a study on markup in the past and I'd like to help with research and writing if that's possible as well.

Slack is part of my workflow already but I'm open to any alternative.

[tunetheweb]

Hope you don't mind me jumping in here.

I'm one of the core contributors for the almanac, working on development and translations, but I also wrote one of the chapters last year, and also copy edited a lot of the chapters last year.

First up I want to say that use whatever works for the team, so take all that I'm going to say with that in mind. However I would strongly encourage GitHub and GoogleDocs over Slack and Email for a lot of the comms. Because while we want to make collaboration as easy as possible for you, we also should bear in mind that people might join and drop out of this, and future years.

For example last year the Markup Chapter had these links:

• Finalize assignments: Chapter 3. Markup #5 - the equivalent to this issue where we picked the team and decided what metrics to look at
• Query metrics: Chapter 3. Markup #84 - where we worked on the metrics
• The SQL we finally came up with for the metrics
• The results
• Write content: Chapter 3. Markup #133 - where we tracked the writing of the chapters
• The chapter in a Google Docs as it was worked on and comments were added

(Most of these are tracked in @rviscomi 's excellent PM sheet from last year).

As you can see there is a wealth of information that is available to you, 2020 authors, analysts and reviewers to help you for this year's chapters to potentially answer questions like why certain metrics weren't looked at last year (were they not considered? Or not possible? Or they were looked at but no interesting data so never made it into the chapter?). You can look at all the metrics from last year, and the results, and – perhaps more importantly – the discussions around them and then decide which ones to look at again this year, which to drop, and what new ones to add - using the above links to help inform you of those decisions.

That wouldn't be possible and a lot of valuable reasoning might be lost if these discussions happened over less linkable, searchable and plus+1-able mediums like Slack and/or Email.

It also means random people (like me here!) can stick our big noses in to try to help. Or you can @ people outside of the immediate chapter team (like @rviscomi @OBTo or myself) or pull in other people outside of the Web Almanac if you've a question for them.

On the other hand, there is a lot to be said for the interactivity for chat so totally understand if you want to go that direction. Just ask you to bear above in mind if you do.

A few other resources to be aware of:

• We have a #web-almanac channel on slack. I encourage you to join, and I presume it's possible to open another channel dedicated to this chapter on that if needs be?
• You can also have a discussion room on GitHub in the team space. Though we tried that for some of the translator teams last year and it wasn't used much to be honest. Not sure I see the benefit over direct discussion in the issues to be honest. But thought I'd throw it out there as an option.

Anyway, will let you all decide as a team but thought I'd throw my 2 cents in based on last year's experience - hope it helps!

[zcorpan]

@j9t

can you confirm that and how you’d like to be involved?

I sign up as reviewer.

I can't commit to the analyst role or author role, but I can help discuss ideas for things to include.

[j9t]

Thanks @bazzadp—this is excellent feedback! Thanks for jumping in :) This is good context and good information to review.

For communication, I signed up for httparchive Slack, and maybe we can indeed just open a channel there to coordinate.

@iandevlin, @catalinred, @zcorpan, great to hear—I’ll update the intro accordingly. @catalinred, would “research” reflect the analyst role?

[catalinred]

@catalinred, would “research” reflect the analyst role?

Actually, I was thinking about writing or reviewing. Can't help with the analyst role.
Let me know where you want me.

[ibnesayeed]

@j9t please count me in as a reviewer. I would have offered to be a co-author, but my plate is too full this year.

[j9t]

Excellent! Thanks for confirming and clarifying, Catalin, Sawood. As we heard from everyone but him I reached out to Manuel directly to check on his interests.

As mentioned before, I’ll be off for a few days now but will use that time to review last year’s chapter as well as the docs. Maybe this is a good time for us all to do that? I have a look particularly at the introductory references as well as Barry’s comment.

Everyone, also @OBTo, @bazzadp, do you have ideas on the analyst role, and who could help with that? I can imagine that’s a bit of a special role in that maybe analysts for other topics could potentially help with, too, if they have bandwidth and are interested in the subject and helping us out?

[iandevlin]

Definitely most of the credit goes to @j9t, who has been an absolute demon. Thank you sir.

[j9t]

Some more work on #1409.

For the results, are we to use https://docs.google.com/spreadsheets/d/1Ta7amoUeaL4pILhWzH-SCzMX9PsZeb1x_mwrX2C4eY8/? I have a vague task on my list to review and clean up the spreadsheet (check formatting, close comments, remove internal notes)—I suppose that can be done then? @rviscomi, @Tiggerito?

[Tiggerito]

I'm not an expert at google sheets. I do know there is an option to copy a sheet and exclude comments in the copy?

[rviscomi]

This is the official sheet that will be linked from the chapter, so make it look how you want readers to see it. Comments are ok for some context and explanations of intended interpretation, but the main thing will be discoverability of metrics. Since so many metrics are packed into single tabs and the tabs are generically named I think that will be the biggest issue. (I did also flag that during analysis but it was outweighed by query costs.) To offset that, I'd encourage you to add metadata to the figures so that we can generate deep links into the sheet from each chart, like the sheets_gid attribute.

[j9t]

Thanks @Tiggerito, @rviscomi. I can’t assess that meta data issue just now but preparing the sheet should generally not be an issue.

[j9t]

(Review of #1409 happily in progress ☺️ ⏳)

[j9t]

Used the time to also go through the results sheet to prepare that. Made styling more consistent, aligned headers, resolved comments, etc.

[tunetheweb]

I've merged in @j9t 's Markup markdown pull request now. Congratulations on being the first 2020 team with a merged chapter!!!

I've uploaded a test deploy for those interested to see what it looks like in all it's glory.

There's still a couple of things to do:

We still need chapter bios from @catalinred and @iandevlin , so if you could submit a PR whenever you get a chance to write these:

almanac.httparchive.org/src/content/en/2020/markup.md

Lines 7 to 9 in a8ef094

	j9t_bio: Jens Oliver Meiert is a web developer and author (<a href="https://leanpub.com/css-optimization-basics"><cite>CSS Optimization Basics</cite></a>, <a href="https://leanpub.com/web-development-glossary"><cite>The Web Development Glossary</cite></a>), who works as an engineering manager at <a href="https://www.jimdo.com/">Jimdo</a>. He’s an expert on web development where he specializes in HTML and CSS optimization. Jens contributes to technical standards and regularly writes about his work and research, particularly on his website, <a href="https://meiert.com/en/">meiert.com</a>.
	# catalinred_bio: @@
	# iandevlin_bio: @@

And we'll be entering the Edit stage next where one of the Editing team will be reviewing the language for grammar, spelling and consistency across the Web Almanac. We'll tag you in the Pull Request for that so you can review the changes and make sure you're comfortable with them.

Thanks again for the tremendous effort here, and for completing this on time (you wouldn't believe the effort in chasing so many teams, so definitely appreciated when we don't have to!)

[j9t]

Very, very, very excited to see this. Thanks @bazzadp and @rviscomi for all your working with me on the latest meters (and yards)!

I’m curious about the editing stage now but will likewise review the outcome again; and I encourage everyone to maybe give the chapter is another read or scan, too.

Exciting! 🥂

[j9t]

(May still leave status updates here, even though this one is closed.)

While there’s a “final” PR open with #1435 (I’ve left some initial but also high-level feedback), I’ve just gone through the spreadsheet again to make sure it’s consistently formatted and such; all good to go from my end.

[rviscomi]

Congratulations everyone, this chapter has been published for early access! https://almanac.httparchive.org/en/2020/markup

[ibnesayeed]

I do not remember when I was supposed to review the content as a reviewer. I was waiting for a call for review.

[j9t]

I do not remember when I was supposed to review the content as a reviewer. I was waiting for a call for review.

The first call was about three weeks ago, followed by a few more updates asking for reviews.

[ibnesayeed]

Thanks @j9t for the reference. I somehow missed it. If it is marked done then that's great, otherwise let me know if it needs further review.

[rviscomi]

@j9t @catalinred @iandevlin and everyone else, in case you're interested, we have an analytics dashboard where you can see how many page views your chapter has received so far: https://datastudio.google.com/s/qoUxiLqPt9U. As of today, the Markup chapter has 1400+ page views and readers spend an average of 3:46 on the page. It's off to a great start!

If readers have feedback/questions/comments about the chapter, be aware that we're sending them to https://discuss.httparchive.org/t/chapter-3-markup/2039. It'd be a good idea to create an account and subscribe to the thread so you can be notified of any new comments.

And a status update on the editing process: #1435 is merged and there are a few unresolved TODOs left in the markdown. Enjoy a bit of a break if you need it, no rush, but it'd be great to resolve all of those before the full launch on December 9.

[Tiggerito]

Just an FYI, I gathered some data on the top meta tag name and properties:

https://docs.google.com/spreadsheets/d/1ram47FshAjzvbQVJbAQPgxZN7PPOPCKIK67VJZCo92c/edit#gid=704388228
https://docs.google.com/spreadsheets/d/1ram47FshAjzvbQVJbAQPgxZN7PPOPCKIK67VJZCo92c/edit#gid=1174860536

[tunetheweb]

@Tiggerito we’re adding the direct links from the Figures (see pull request #1570 but still early days). While working on this I noticed you haven’t included the sql_files param to the Graphics and only to the Tables. Can you do a pull request to add these params to each figure_markup call? That way people will be able to see your hard work!

Also (for everyone), you probably don’t want to hear more suggestions, but another thing I noticed was that the chapter starts with lots of nice graphs but from about halfway moves to tables and only has tables from then on. Is there any data we could present as charts instead of tables, or additional tables, to break up the chapter a bit?

[Tiggerito]

@bazzadp done