docs: emphasize some points on what makes a good audit #10376
Conversation
| @@ -8,13 +8,33 @@ Lighthouse audits that surface in the report should be: | |||
| - Contribute significantly towards making the mobile web experience better for end users. | |||
| - Not have a significant impact on our runtime performance or bundle size. | |||
| - Something that is new, and not something that is already measured by existing audits. | |||
| - Important for our strategic goals as a product. | |||
There was a problem hiding this comment.
This is another way to say "we have veto control on what lands in core", which goes without saying. low-value to have here.
| | `'thumbnail'` | Image Resource | same as above, but we show a thumbnail | | ||
| | `'link'` | - | arbitrary link / url combination | | ||
| | `'text'|'ms'|'numeric'` | - | | | ||
|
|
There was a problem hiding this comment.
i kinda think it'd be cool to have a screenshot or two of examples. in two screenshots (*images and tap-targets) you be able to show off thumbnails, url, numeric, node.
oh i guess one more for source-location.
but showing kinda whets the appetite :)
docs/new-audits.md
Outdated
| - Not use 3rd party APIs for completing the audit check. | ||
|
|
||
| ## Actionable | ||
|
|
||
| 1. When failing, specific advice should be given. If an audit can fail in multiple ways, each way should have a specific error message. |
There was a problem hiding this comment.
i dont think its an "error message" because that indicates a runtime problem with the audit.
i dont know what the right words are but.. "users should understand the specifics of why this case is failing"
docs/new-audits.md
Outdated
| - Not use 3rd party APIs for completing the audit check. | ||
|
|
||
| ## Actionable |
There was a problem hiding this comment.
actuallly... lets put this actionability section in the plugins.md. that has a bigger audience than this doc. we can of course add a link from new-audits to the section.
There was a problem hiding this comment.
I already added a link from the plugin doc -> new audit doc. I don't think this file should exist if we put important new-audit advice elsewhere. weird bifurcation imo
There was a problem hiding this comment.
we have two docs for two "conceivable" audiences:
- audience who wants to build a plugin full of their own audits
- audience who wants to propose a new audit to core (but doesnt want to implement as a plugin)
The actionability stuff is relevant to both of them.
I'm just saying the 1st audience is bigger than the second. Really I think this actionability stuff is a Must-read for both audiences but i'd rather the plugin folks see it. The risk is greater for them; they could end up making a useless audit. Whereas the proposers just need us to provide feedback to improve their proposal.
The new-audit doc still stands on its own afterwards.
i'm happy to do it if you'd rather not spend the time. (though i would like to convince you its better this way. :)
Co-Authored-By: Paul Irish <[email protected]>
adding some stuff here. concerned that we aren't emphasizing the important bits
https://github.com/GoogleChrome/lighthouse/blob/audit-docs/docs/new-audits.md