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
610 stars 168 forks source link

Embed data visualizations in chapters #237

Closed rviscomi closed 4 years ago

rviscomi commented 4 years ago
  1. Find a given metric in the chapter's public results spreadsheet and use pivot tables to get the data ready for visualizing. Usually this means adding desktop/mobile as separate columns.
  2. Select the appropriate chart from the Data Viz Style Guide sheet and copy it into the metric's sheet.
  3. Update the chart's data source and labels accordingly. Resize the chart so it is no more than 600px wide, using existing charts of known width as a guide if needed. (600px is the default width for new charts.)
  4. From the chart's three-dot menu, select "Publish chart" and copy the HTML.
  5. Paste the HTML into the markdown

All graphics in a chapter (charts, images, etc) should be manually wrapped in a figure element with a unique ID that is sequentially numbered. All figure elements have a figcaption that describes the contents of the figure, prefixed by the figure number.

Interactive figures (embedded charts from Sheets)

Interactive figures should have a visually-hidden element for screen reader users. Level of detail here should be to convey the main visual takeaways of the chart but not overly descriptive. Add the aria-labelledby="fig1-caption" attribute to the iframe element and create a corresponding element to describe the figure.

These figures must also have a corresponding anchor/image linking to a static version of the figure. They can reuse the same visually-hidden element for screen reader users. Images should have an explicit width equivalent to the iframe width.

CSS will be used to ensure the interactive figure is shown to desktop users and the static figure is shown to mobile users.

<figure>
  <iframe aria-labelledby="fig1-caption" width="600" height="371" seamless frameborder="0" scrolling="no" src="https://docs.google.com/spreadsheets/d/e/2PACX-1vSQlf3_ySLPB5322aTumUZhbVGdaUdkmi1Hs4bYuO3Z1kqM4xspx7REbwXukwPd_tsOSg6oImzpYLM9/pubchart?oid=115935793&amp;format=interactive"></iframe>
  <a href="/static/images/2019/07_Performance/fig1.png" class="fig-mobile">
    <img src="/static/images/2019/07_Performance/fig1.png" aria-labelledby="fig1-caption"  width="600">
  </a>
  <div id="fig1-caption" class="visually-hidden">Figure 1. Descriptive text for screen reader users here.</div>
  <figcaption>Figure 1. Distribution of websites' fast, moderate, and slow FCP performance.</figcaption>
</figure>

Static figures (images)

Static images should be wrapped in an anchor tag to be expandable for users on small screens. Rather than a visually hidden descriptor images can simply use the alt attribute for screen reader users. Images should have an explicit width when possible.

<figure>
  <a href="/static/images/2019/01_JavaScript/example.jpg">
    <img src="/static/images/2019/01_JavaScript/example.jpg" alt="Descriptive text for screen reader users here." width="600">
  </a>
  <figcaption>Figure 4. Timeseries of JavaScript bytes for the median web page since 2010.</figcaption>
</figure>
rviscomi commented 4 years ago

Edit: See https://github.com/HTTPArchive/almanac.httparchive.org/issues/237#issue-512661694 above for steps to embed data viz

foxdavidj commented 4 years ago

After copy-editing is done I'll help out with this.

Regarding improving the mobile UX, I'm leaning towards the route of generating static images that display the individual values when possible (e.g., bar graphs). They'd resize well, may be quicker to implement, and give the benefit of being highly shareable.

rviscomi commented 4 years ago

Also assigning @paulcalvano to help with the data viz (thanks Paul!).

Some chapters rely only on images and/or data tables, so there might not be any charts to generate/embed but we still need to ensure that they use the figure and caption consistently.

tunetheweb commented 4 years ago

but we still need to ensure that they use the figure and caption consistently.

Yes I noticed tables in my chapter overflow on mobile whereas wrapping in a figure overflows with scroll which is much better! Same with wide code snippets which need to have a class added: <pre class='code-block'>

rviscomi commented 4 years ago

@colinbendell FYI about our data viz process

paulcalvano commented 4 years ago

I attempted to convert two static images using this process, but the embedded images don't display in markdown. The test I made was to use the following:

<iframe aria-labelledby="fig1-caption" width="600" height="371" seamless frameborder="0" scrolling="no" src="https://docs.google.com/spreadsheets/d/e/2PACX-1vQNIyMEGYE_1W0OdFYLIKsxg6M3o_ZsTTuaX73Zzv6Alw4x4D6oH0jdg9BSgw-jy4E-MmX_Qaf-B98W/pubchart?oid=2052550005&amp;format=interactive">
  <div class="visually-hidden">Gzip and Brotli are the most common forms of text compression on desktop web pages.</div>
  <figcaption>Figure 1. Compression algorithms on desktop pagers</figcaption>
</iframe>
</figure>

<figure>
<iframe aria-labelledby="fig2-caption" width="600" height="371" seamless frameborder="0" scrolling="no" src="https://docs.google.com/spreadsheets/d/e/2PACX-1vQNIyMEGYE_1W0OdFYLIKsxg6M3o_ZsTTuaX73Zzv6Alw4x4D6oH0jdg9BSgw-jy4E-MmX_Qaf-B98W/pubchart?oid=2012654579&amp;format=interactive">
  <div class="visually-hidden">Gzip and Brotli are the most common forms of text compression on mobile web pages.</div>
  <figcaption>Figure 2. Compression algorithms on mobile pages</figcaption>
</iframe>
</figure>

You can see this at the end of the "Compression Algorithms" section in this fork - https://github.com/paulcalvano/almanac.httparchive.org/blob/master/src/content/en/2019/compression.md

Any idea what I'm doing wrong here?

rviscomi commented 4 years ago

After making changes to the markdown file you need to convert them to markup by running npm run generate. More info in the readme.

Also your visually-hidden div is missing an ID corresponding to the aria-labelledby above. This was my fault, I omitted it from the example code. I've updated it and also added an example of an image figure.

rviscomi commented 4 years ago

I've updated https://github.com/HTTPArchive/almanac.httparchive.org/issues/237#issue-512661694 with canonical steps for data viz.

image

This is a mobile view of the old and new data viz processes. On top it's the iframe overflowing and on the bottom it's the image fallback for mobile. Much more legible!!

foxdavidj commented 4 years ago

I can handle some of this tomorrow morning

On Fri, Nov 8, 2019, 18:16 Rick Viscomi notifications@github.com wrote:

I've updated #237 (comment) https://github.com/HTTPArchive/almanac.httparchive.org/issues/237#issue-512661694 with canonical steps for data viz.

— You are receiving this because you were assigned. Reply to this email directly, view it on GitHub https://github.com/HTTPArchive/almanac.httparchive.org/issues/237?email_source=notifications&email_token=AAFHFS5M5PDH3NCOU4OU6ODQSX6N5A5CNFSM4JFHGAO2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEDTXMZY#issuecomment-552040039, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAFHFS5DZGZTZMPSZ4FCG7TQSX6N5ANCNFSM4JFHGAOQ .

foxdavidj commented 4 years ago

Hey everyone, I was able to finish adding data viz to the JavaScript chapter but sadly wont have time to help add the other chapters. Got to catch a flight in about 10 hours 💦

tunetheweb commented 4 years ago

FYI noticed the fallback images for Security chapter don’t exist yet. It’s not ticked as done in first comment so may already be on your to do list, but it is published so thought best to comment in case you thought done.

ymschaap commented 4 years ago

Who could pick up the SEO chapter?

tunetheweb commented 4 years ago

Who could pick up the SEO chapter?

The format of these might be changing if https://github.com/HTTPArchive/almanac.httparchive.org/pull/491 is accepted. So might be better to wait for a decision on that? Could do with more eyes on that if anyone else wants to help code review too?

Then again it's backwards compatible and easy to convert from old format to new so could just work on visualisations and then convert later depending on decision on https://github.com/HTTPArchive/almanac.httparchive.org/pull/491?

tunetheweb commented 4 years ago

@rviscomi any reason this is still open? Third Party chapter looks done, or are you planning on adding more to this?

rviscomi commented 4 years ago

@bazzadp many of the data viz placeholders for the 3P chapter are commented out, but still outstanding. I need to chat with @patrickhulce about the data first.

tunetheweb commented 4 years ago

@bazzadp many of the data viz placeholders for the 3P chapter are commented out, but still outstanding. I need to chat with @patrickhulce about the data first.

@rviscomi / @patrickhulce gentle nudge. Only see two comments about graphics for 5_11 and 5_12. We ever going to add those or shall we just say the chapter is as complete as it's going to get and close this issue?

rviscomi commented 4 years ago

Sorry, this slipped me. I would still love to resolve the data viz for this chapter. @patrickhulce let me know if you have time to chat. Or if you're happy leaving it as-is we can close this out.

tunetheweb commented 4 years ago

Should we not at least add Figure 6 so the figure numbering is correct? Currently we jump straight from Figure 5 to Figure 7.

rviscomi commented 4 years ago

I'd still like to get the data viz resolved but the results don't align with the analysis AFAICT, so we need to chat with Patrick to get that resolved before we're able to add new figures. I closed this since there was no activity and it's about 6 months overdue.