Improve docs rendering performance by addressing PageSpeed Insights issues

[Valloric]

Results from PageSpeed.

The easy ones are setting up cache expiration times for the font & css files and minifying the CSS. Eliminating render-blocking JavaScript and CSS in above-the-fold content is a bit harder, but shouldn't be too much work for a static site.

[huonw]

For triage/future comparison purposes, the current state is:

Desktop

91 / 100

Consider Fixing:

• Eliminate render-blocking JavaScript and CSS in above-the-fold content
• Leverage browser caching
• Minify CSS

Mobile

58/100 User Experience

Should Fix:

• Use legible font sizes
• Size tap targets appropriately
• Configure the viewport

81/100 Speed

Should Fix:

• Eliminate render-blocking JavaScript and CSS in above-the-fold content

Consider Fixing:

• Leverage browser caching
• Minify CSS

cc #20961

[Valloric]

Note the "how to fix" links on the PageSpeed site for each issue; clicking on them will provide more information, like a list of all static resources on the page that have been detected as not currently using browser caching etc. That extra debug info is what I've personally found to be a goldmine from PageSpeed.

[steveklabnik]

re-tagging as infrastructure and rustbook, as those are the two things that would need changed for this.

[brson]

Do we have an in-tree way to minify CSS already? Hm, since this is part of rustbook, I guess the minifier needs to be in rustbook. Do these issues only apply to the book or to rustdoc as well?

If this is a rustbook issue maybe it's not even worth fixing. Just wait to convert everything to mdbook.

[steveklabnik]

I don't believe so.

On Jun 27, 2016, 18:08 -0400, Brian Andersonnotifications@github.com, wrote:

Do we have an in-tree way to minify CSS already?

—
You are receiving this because you commented.
Reply to this email directly,view it on GitHub(#20962 (comment)), ormute the thread(https://github.com/notifications/unsubscribe/AABsir1M39J39kBpIkWNlkP8urMS_4oTks5qQEnegaJpZM4DQ7HC).

[steveklabnik]

Removing the rustbook tag, as now we use mdbook, so this would be an upstream thing.

[kzys]

Rustdoc's PageSpeed results

While Rustdoc itself can address "Eliminate render-blocking JavaScript and CSS in above-the-fold content" and "Minify CSS", "Leverage browser caching" and "Enable compression" depend on the http server's configuration (CloudFront and S3?).

[workingjubilee]

I have been poking around improvements to rustdoc for this.

First, for the ownership page: long since moved, but checking the stats for Understanding Ownership: What is Ownership? gives us an overall Mobile 73, Desktop 95. So, better, even though it's a much more complex page now! Nice. It still recommends "Eliminate render-blocking resources" and "Serve static assets with an efficient cache policy" though.

But I have been focused on std's API docs and referencing Iterator's page as a particularly problematic case in terms of doc rendering times.

"Core Web Vitals" have been added to PageSpeed Insights.

• First Contentful Paint: Important.
• Largest Contentful Paint: Important.
• First Input Delay: scrolling/zooming are not covered by FID, so not a big concern.
• Cumulative Layout Shift: Maybe? Great layout shifts long after loading are bad, but for Rust's API docs that's mostly about making sure core fonts get loaded quickly. Painting speed and legibility should come well before CLS.

Field Data

This is gathered from recent visits that Chrome's telemetry reports, basically.

Mobile

The Chrome User Experience Report does not have sufficient real-world speed data for this page.
Origin Summary: Over the last 30 days, all pages served from this origin pass the Core Web Vitals assessment. To view suggestions tailored to each page, analyze individual page URLs.

Metric	Average	% Good	% Needs Improvement	% Poor
First Contentful Paint (FCP)	0.8s	83%	15%	2%
Largest Contentful Paint (LCP)	1s	97%	2%	1%
First Input Delay (FID)	14ms	95%	4%	1%
Cumulative Layout Shift (CLS)	0	89%	7%	4%

Desktop

(Over the last 30 days, field data shows that this page does not pass the Core Web Vitals assessment.)

Metric	Average	% Good	% Needs Improvement	% Poor
First Contentful Paint (FCP)	0.5s	94%	5%	1%
Largest Contentful Paint (LCP)	1s	97%	2%	1%
First Input Delay (FID)	19ms	85%	10%	4%
Cumulative Layout Shift (CLS)	0.42	16%	3%	81%

Lab Data

It should be noted that Lab Data and most diagnostics are not consistent between runs of PageSpeed Insights. I ran it a few times and took a median.

Metric	Mobile	Desktop
Overall Score	41	79
First Contentful Paint	1.8s	1.0s
Speed Index	2.7s	1.0s
Largest Contentful Paint	7.2s	2.2s
Time to Interactive	9.3s	2.3s
Total Blocking Time	1850ms	160ms
Cumulative Layout Shift	0	0.445

As we can see, CLS mostly exists on screens that are bigger, FID is low, TBT is not great, but our FCP is good and our LCP could use improvement.

Opportunities & Diagnostics

Metric	Resources	Mobile	Desktop
Eliminate render-blocking resources	--	0.86s	0.36s
Ensure text remains visible during webfont load	--	150ms	160ms
Remove unused JavaScript	8 kb	0.15s	--
Avoid an excessive DOM size	14,545 elements	--	--
Serve static assets with an efficient cache policy	22 resources	--	--
Minimize main-thread work	--	6.3s	--
Avoid chaining critical requests	15 chains	510ms	590ms
Keep request counts low and transfer sizes small	23 requests; 1,038 KB	--	--

[workingjubilee]

Mostly rustdoc is about typography. Improving font loading may be the biggest win in actual performance (I notice a long block when loading a page in actual usage, which goes away when I twiddle with the CSS to use font-display options, but my initial PR... might have gone a bit far).

The std API docs apparently don't get a ton of mobile visitors since browsing several "obvious" pages that might be referenced even on mobile doesn't get per-page Field Data. Likewise with https://docs.rs/rand, which is surprising, though https://docs.rs itself does. So, if that's correct, then mostly whatever is a problem on both desktop and mobile should be a concern. Anything that improves both.

Cache-Control headers are still needed on the server configuration side.
Doing something cleverer re: resource arrangement and loading might help.
Doing something cleverer re: html/CSS (to minimize the DOM size) might help.

[Valloric]

I recommend this recent article that goes into great depth on the fastest way to load external fonts from Google Fonts (which I believe the rust docs use): https://csswizardry.com/2020/05/the-fastest-google-fonts/

[workingjubilee]

It does not.

The article is an OK summary in spite of that but there are other issues which I have discovered in actually implementing such changes which are long and off-topic.