Incorporating Stack Packs into web.dev

[philkrie]

cc: @housseindjirdeh @paulirish @egsweeny

What page(s) need to be updated?

All Lighthouse Opportunities and Diagnostics pages in web.dev that have applicable stack pack recommendations.

Why is this update needed?

Stack packs are Google approved, framework specific suggestions that appear in Lighthouse audits within the Opportunities, Diagnostics, and Passed Audits tab. However, they aren't mentioned in the relevant web.dev articles. This would make the web.dev resources more complete, provide a space for additional elaboration on framework specific recommendations, and surface stack pack recommendations/best practices in more places for users to discover.

What's the deadline?

None, just want to start a discussion :)

[paulirish]

All existing stack pack descriptions https://gist.github.com/paulirish/b2332e4658f0732a95b13e1eb7ce609f

[housseindjirdeh]

Thanks for starting the discussion here @philkrie! Definitely think it's worthwhile to surface mentions of stack packs in the appropriate opportunities/diagnostics pages in the performance audits section.

What would be the best way to surface this? Some ideas:

1. We could just have a note at the top of each article that mentions that additional stack-specific recommendations will provided if detected:

2. Do we want to show stack pack recommendations in more detail? Maybe a section at the end of each appropriate article?

With either approach, we'll have to remember to keep things updated as new stack packs are added or modified.

@philkrie @kaycebasques wdyt?

[philkrie]

Great ideas! Where would the "Learn More" link in the first example link to? If there's a single consolidated web.dev page (or the gist Paul linked) that we could send users there. Instead of placing a section in each page, we can have a single page with each section and link to an anchor in that page. That would make it easier to maintain, while reducing the amount of content that needs to be added to each existing page. Thoughts?

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed in 7 days if no further activity occurs. To prevent this from happening, leave a comment.

[paulirish]

Instead of placing a section in each page, we can have a single page with each section and link to an anchor in that page. That would make it easier to maintain, while reducing the amount of content that needs to be added to each existing page.

Maintenance-wise: It's true that single-page is easier, but... I don't think it's better for the user. So I'm inclined to just distribute the descriptions to their home.

I think the above mocks are great. IIRC kayce wants to rely on TOCs more, so instead of the first screenshot.. we'd just have a "Stack-specific guidance" item in the TOC which'd link down to the header of the 2nd screenshot. Seems cool to me.

[philkrie]

Great, that sounds good to me! @kaycebasques please let us know your thoughts. Houssein and I can divide and conquer; I'm not too experienced w/ the web.dev repo, but it looks like we could import an njk file. Is there a filtering functionality we could use so that we can just maintain a single file w/ all of the stack packs?

[paulirish]

I wrote some code on the weekend that grabs all stackpack data and adds it into the correct markdown file. No fancy importing required. https://github.com/GoogleChrome/lighthouse/compare/updatewebdevwstackpack

It needs a little bit more work (mostly the filesystem path stuff going from LH repo to web.dev repo). But it preps all changes. If we wanted to automate this into something that makes a branch/commit/PR.. that'd be additional.

Is there a filtering functionality we could use so that we can just maintain a single file w/ all of the stack packs?

the file could get some small tweaks to also create a single unified file, too.

[kaycebasques]

Seeing this convo for the first time. Will review tomorrow.

[kaycebasques]

Regarding where the stack pack guidance would live, this seems most reasonable to me:

• We add the usual "Learn more" doc to the end of each stack pack description (within the Lighthouse report UI).
• We add sections of content to the existing audit guides.

Take the render-blocking resources audit for example. The WordPress stack pack "Learn more" link would go to https://web.dev/render-blocking-resources/#wordpress (and we would create a section with that ID).

@philkrie & @housseindjirdeh if you can draft the content that'd be a big help

[paulirish]

I put up a PR to "add sections of content to the existing audit guides." #4093

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed in 7 days if no further activity occurs. To prevent this from happening, leave a comment.

[kaycebasques]

Not stale. Just swamped!

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed in 7 days if no further activity occurs. To prevent this from happening, leave a comment.

[philkrie]

un-staling

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed in 7 days if no further activity occurs. To prevent this from happening, leave a comment.

[philkrie]

bump