docs(user-flows): refactor document #14021

paulirish · 2022-05-18T00:35:15Z

building on adam's great work in #14009 I wanted to try to frontload the mode descriptions so devtools folks understand these concepts without having to see the nodejs api.

Changes:

description/differentiation of 3 modes is front-and center.
denser information.
added various illustrations for the modes
cropped devtools images to just the important bits
fixed a few bugs in the pptr scripts
redid the "example userflow image"
dropped the very odd workflow image

I'm pretty happy with how it stands now. decent job with both audiences: 1) devtools folks clicking through on "wtf is this mode selector" and 2) folks wanting to properly analyze userflows with the js api

preview: https://github.com/GoogleChrome/lighthouse/blob/dt-user-flows-doc-me/docs/user-flows.md

adamraine

Why add the images to the assets folder? They're not the same images used in the doc.

adamraine · 2022-05-18T16:46:42Z

docs/user-flows.md


 ```js
 import {writeFileSync} from 'fs';
 import puppeteer from 'puppeteer';
-import api from 'lighthouse/lighthouse-core/fraggle-rock/api.js';
+import lighthouse from 'lighthouse/lighthouse-core/fraggle-rock/api.js';


I intentionally changed this to api because it's not the same as doing import lighthouse from 'lighthouse'

yeah that makes sense. but i also think api is too general. it looks 'fine' on this line but then later with api.startFlow it's lost its identity

lighthouseapi ? lhapi?

we should also fix the export so that import lighthouse from 'lighthouse' actually would work for all this. i feel good about doing that for v10

we should also fix the export so that import lighthouse from 'lighthouse' actually would work for all this. i feel good about doing that for v10

Ok, in that case we can leave this with plans to update the docs once startFlow is exported via the default entry point.

docs/user-flows.md

adamraine · 2022-05-18T17:07:23Z

docs/user-flows.md

-Navigation reports analyze a single page load. Navigation is the most common type of report you'll see. In fact, all Lighthouse reports prior to v9 are navigation reports.
+|  |  |
+|---|---|
+| Navigation | <small> *Benefits* <br> ✅ Provides an overall performance score and all metrics.<br>✅ Contains the most advice of all report types (both time-based and state-based audits are available).<br> *Limitations* <br> 🤔 Cannot analyze form submissions or single page app transitions.<br>🤔 Cannot analyze content that isn't available immediately on page load.<br> *Use Cases* <br> 👍 Obtain a Lighthouse Performance score.<br>👍 Measure Performance metrics (First Contentful Paint, Largest Contentful Paint, Speed Index, Time to Interactive, Cumulative Layout Shift, Total Blocking Time).<br>👍 Assess Progressive Web App capabilities.</small> |


If we're going to use a table here, can benefits/limitations/use cases each have there own column? If that doesn't look good then maybe we're better off using headings/subheadings for this.

i tried the per-column look but there's just too much line-wrapping and it looked a lil whack.

(well.. what i had was slightly diff but the wrapping is similar to what it'd be:)

Lemme try some clearer headings…

yup better now

docs/user-flows.md

Co-authored-by: Adam Raine <[email protected]>

paulirish · 2022-05-19T20:15:19Z

Why add the images to the assets folder? They're not the same images used in the doc.

true. I just wanted to have them in a more accessible place than locked up in figma.

adamraine · 2022-05-19T21:34:16Z

docs/user-flows.md

-### Navigation
+| | |
+|:---:|---|
+| Navigation <br> <img src="https://user-images.githubusercontent.com/39191/168928225-f2157fda-5131-4bd0-9121-b1a0b2f869a7.png" height="96" width="141">  | **Benefits** <br>  ✅ Provides an overall performance score and all metrics.<br>✅ Contains the most advice of all report types.<br><br> **Limitations** <br>  🤔 Cannot analyze form submissions or single page app transitions.<br>🤔 Cannot analyze content that isn't available immediately on page load.<br><br> **Use Cases** <br>  👍 Obtain a Lighthouse Performance score.<br>👍 Measure all performance metrics.<br>👍 Assess Progressive Web App capabilities. |


Could you also add these images to the more detailed sections below this table so there is a god visual callout. I was thinking something similar to the "Creating a Flow" section.

good idea. done

docs/user-flows.md

adamraine · 2022-05-19T21:38:42Z

docs/user-flows.md

+|:---:|---|
+| Navigation <br> <img src="https://user-images.githubusercontent.com/39191/168928225-f2157fda-5131-4bd0-9121-b1a0b2f869a7.png" height="96" width="141">  | **Benefits** <br>  ✅ Provides an overall performance score and all metrics.<br>✅ Contains the most advice of all report types.<br><br> **Limitations** <br>  🤔 Cannot analyze form submissions or single page app transitions.<br>🤔 Cannot analyze content that isn't available immediately on page load.<br><br> **Use Cases** <br>  👍 Obtain a Lighthouse Performance score.<br>👍 Measure all performance metrics.<br>👍 Assess Progressive Web App capabilities. |
+| Timespan <br> <img src="https://user-images.githubusercontent.com/39191/168928251-c7025cd5-0086-4db8-ae52-95a5b5675adf.png" height="96" width="141">  | **Benefits** <br>  ✅ Provides timerange-based metrics such as TBT, CLS and INP.<br>✅ Analyzes any period of time, including user interactions or single page app transitions.<br><br> **Limitations** <br>  🤔 Does not provide an overall performance score.<br>🤔 Cannot analyze moment-based performance metrics (e.g. Largest Contentful Paint).<br>🤔 Cannot analyze state-of-the-page issues (e.g. no Accessibility category)<br><br> **Use Cases** <br>  👍 Measure layout shifts and JavaScript execution time on a series of interactions.<br>👍 Discover performance opportunities to improve the experience for long-lived pages and SPAs. |
+| Snapshot <br> <img src="https://user-images.githubusercontent.com/39191/168931653-b45e0b6b-c5bd-4d8d-85b6-fee8425186a0.png" height="96" width="141">  | **Benefits** <br>   ✅ Analyzes the page in its current state.<br><br> **Limitations** <br>  🤔 Does not provide an overall performance score or metrics.<br>🤔 Cannot analyze any issues outside the current DOM (e.g. no network, main-thread, or performance analysis).<br><br> **Use Cases** <br>  👍 Find accessibility issues in single page applications or complex forms.<br>👍 Evaluate best practices of menus and UI elements hidden behind interaction. |


This is kinda hard to read/review from the md side. Is it possible to use newlines to separate each bullet point?

unfortunately i can't. but the text is the same as what it was. (except i shortened a few metric references)

adamraine · 2022-05-19T21:40:48Z

docs/user-flows.md

-So far we've seen individual Lighthouse modes in action. The true power of flows comes from combining these building blocks into a comprehensive flow to capture the user's entire experience.
-
-### Selecting Boundaries
+<img src="https://user-images.githubusercontent.com/39191/168931109-5ae80620-7464-4d98-a834-71169a5b6a61.png" height=300>


Can this guy be a little smaller, maybe 200px?

matches the rest now. 240px

adamraine · 2022-05-19T21:45:48Z

docs/user-flows.md

-### Navigation
+| | |
+|:---:|---|
+| Navigation <br> <img src="https://user-images.githubusercontent.com/39191/168928225-f2157fda-5131-4bd0-9121-b1a0b2f869a7.png" height="96" width="141">  | **Benefits** <br>  ✅ Provides an overall performance score and all metrics.<br>✅ Contains the most advice of all report types.<br><br> **Limitations** <br>  🤔 Cannot analyze form submissions or single page app transitions.<br>🤔 Cannot analyze content that isn't available immediately on page load.<br><br> **Use Cases** <br>  👍 Obtain a Lighthouse Performance score.<br>👍 Measure all performance metrics.<br>👍 Assess Progressive Web App capabilities. |


I'm not sure we need a "Benefits" and and "Use Cases" section for each mode. A lot of the points are repeated between the two sections. WDYT about just having a "Use Cases" and "Limitations" section?

yes i love it. i'm always a fan of brevity. i merged those two and it looks a lot better now.

adamraine · 2022-05-19T21:47:11Z

docs/user-flows.md


 ```js
 import {writeFileSync} from 'fs';
 import puppeteer from 'puppeteer';
-import api from 'lighthouse/lighthouse-core/fraggle-rock/api.js';
+import lighthouse from 'lighthouse/lighthouse-core/fraggle-rock/api.js';


we should also fix the export so that import lighthouse from 'lighthouse' actually would work for all this. i feel good about doing that for v10

Ok, in that case we can leave this with plans to update the docs once startFlow is exported via the default entry point.

Co-authored-by: Adam Raine <[email protected]>

…flows-doc-me

adamraine

Overall looks good

docs/user-flows.md

Co-authored-by: Adam Raine <[email protected]>

connorjclark · 2022-05-27T23:07:14Z

docs/user-flows.md

@@ -14,7 +14,7 @@ In these cases, you want Lighthouse on a _flow_, not just a page load.

 Lighthouse can now run in three modes: navigations, timespans, and snapshots. Each mode has its own unique use cases, benefits, and limitations. Later, you'll create a flow by combining these three core report types.

-* **Navigation mode** analyzes a single page load. Prior to v9.6.1, all Lighthouse runs were essentially in this mode.
+* **Navigation mode** analyzes a single page load. Prior to v9.6.0, all Lighthouse runs were essentially in this mode.


Reword? I can't tell at a glance without employing multiple brain cells if this is exclusive or not :') "Starting in..." would work better

how about

Navigation mode analyzes a single page load. It should feel familiar as all Lighthouse runs prior to v9.6.0 were essentially in this mode. Even in v9.6.0 and onwards, it remains the default.

adamraine

Sorry, some last minute thoughts

docs/user-flows.md

connorjclark · 2022-05-31T23:09:25Z

nit: refactor document -> summarize what changed? :)

paulirish · 2022-06-13T19:57:14Z

nit: refactor document -> summarize what changed? :)

a lot changed. i added a summary to the PR description. don't know what else to call it, but feel free to edit the title.

adamraine and others added 13 commits May 16, 2022 13:43

docs(user-flows): add instructions for DevTools

48d4cdb

heading

c1b6cbb

period

4897fdf

npte

ef9c8d2

Merge branch 'master' into dt-user-flows-doc

b1e3bef

start

7955a8d

import from figma

86c73e6

imageoptim. lossless

f853e43

png now

5d4f8a0

horiz table layout

dd01356

inline image

f109fa9

3 modes lookin pretty clean

2ef349e

remaining cleanup. drop flowchart diagram

d997187

paulirish requested a review from a team as a code owner May 18, 2022 00:35

paulirish requested review from adamraine and removed request for a team May 18, 2022 00:35

adamraine reviewed May 18, 2022

View reviewed changes

adamraine and others added 2 commits May 19, 2022 10:33

Merge branch 'master' into dt-user-flows-doc

50e9fb8

Update docs/user-flows.md

ba1dbf8

Co-authored-by: Adam Raine <[email protected]>

vercel bot deployed to Preview May 19, 2022 19:49 View deployment

Update docs/user-flows.md

87f2992

Co-authored-by: Adam Raine <[email protected]>

vercel bot deployed to Preview May 19, 2022 19:53 View deployment

paulirish added 2 commits May 19, 2022 13:10

diagram

11da116

better table

5aa4280

vercel bot deployed to Preview May 19, 2022 20:13 View deployment

an empty table header is required. because markdown parsing. :/

3155626

vercel bot deployed to Preview May 19, 2022 20:15 View deployment

adamraine reviewed May 19, 2022

View reviewed changes

Update docs/user-flows.md

b60f50e

Co-authored-by: Adam Raine <[email protected]>

vercel bot deployed to Preview May 19, 2022 22:09 View deployment

adamraine and others added 2 commits May 24, 2022 09:45

Merge branch 'master' into dt-user-flows-doc

ae8abb2

feedback

b7f5c68

vercel bot deployed to Preview May 26, 2022 19:33 View deployment

paulirish force-pushed the dt-user-flows-doc-me branch from 6ea4f5a to b7f5c68 Compare May 26, 2022 19:35

Merge remote-tracking branch 'origin/dt-user-flows-doc' into dt-user-…

252317b

…flows-doc-me

vercel bot deployed to Preview May 26, 2022 19:36 View deployment

adamraine approved these changes May 26, 2022

View reviewed changes

docs/user-flows.md Outdated Show resolved Hide resolved

Update docs/user-flows.md

9fc9a8d

Co-authored-by: Adam Raine <[email protected]>

vercel bot deployed to Preview May 27, 2022 23:05 View deployment

connorjclark reviewed May 27, 2022

View reviewed changes

Base automatically changed from dt-user-flows-doc to master May 27, 2022 23:18

paulirish added 2 commits May 27, 2022 16:41

Merge remote-tracking branch 'origin/master' into dt-user-flows-doc-me

bfd70b2

the rewording i suggested back to connor

a9b620f

vercel bot deployed to Preview May 27, 2022 23:44 View deployment

Merge remote-tracking branch 'origin/master' into dt-user-flows-doc-me

a244d18

vercel bot deployed to Preview May 31, 2022 20:11 View deployment

adamraine reviewed May 31, 2022

View reviewed changes

docs/user-flows.md Outdated Show resolved Hide resolved

docs/user-flows.md Outdated Show resolved Hide resolved

adamraine mentioned this pull request Jun 13, 2022

core(user-flow): start/end navigation functions #13966

Merged

paulirish added 2 commits June 13, 2022 12:51

adams lastmin feedback

ebdc37d

Merge remote-tracking branch 'origin/master' into dt-user-flows-doc-me

cf34f05

vercel bot deployed to Preview June 13, 2022 19:52 View deployment

paulirish added the land-when-ci-is-green label Jun 13, 2022

devtools-bot merged commit 488c40f into master Jun 13, 2022

devtools-bot deleted the dt-user-flows-doc-me branch June 13, 2022 20:14

devtools-bot removed the land-when-ci-is-green label Jun 13, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(user-flows): refactor document #14021

docs(user-flows): refactor document #14021

paulirish commented May 18, 2022 •

edited

Loading

adamraine left a comment

adamraine May 18, 2022

paulirish May 19, 2022

adamraine May 19, 2022

adamraine May 18, 2022

paulirish May 19, 2022

paulirish May 19, 2022

paulirish commented May 19, 2022

adamraine May 19, 2022

paulirish May 26, 2022

adamraine May 19, 2022

paulirish May 26, 2022

adamraine May 19, 2022

paulirish May 26, 2022

adamraine May 19, 2022

paulirish May 26, 2022

adamraine May 19, 2022

adamraine left a comment

connorjclark May 27, 2022 •

edited

Loading

paulirish May 27, 2022

adamraine left a comment

connorjclark commented May 31, 2022

paulirish commented Jun 13, 2022

docs(user-flows): refactor document #14021

docs(user-flows): refactor document #14021

Conversation

paulirish commented May 18, 2022 • edited Loading

adamraine left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

paulirish commented May 19, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

adamraine left a comment

Choose a reason for hiding this comment

connorjclark May 27, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

adamraine left a comment

Choose a reason for hiding this comment

connorjclark commented May 31, 2022

paulirish commented Jun 13, 2022

paulirish commented May 18, 2022 •

edited

Loading

connorjclark May 27, 2022 •

edited

Loading